:Add signatures to URLs

Usage notes

• If you use a signed URL to share data, the data can be accessed by all users on the Internet within the validity period of the signed URL. We recommend that you assess the risks in advance.
• OSS does not allow you to contain a signature in the URL of a specific resource and in the Authorization header of a request for the resource at the same time.
• You can add signatures to URLs so that third-party users can use the signed URLs to initiate PUT and GET requests.
• You can generate a presigned URL for a PUT request to check whether the intended content is uploaded. If you use an OSS SDK to generate a presigned URL for a request, the OSS SDK calculates the MD5 hash of the request body and includes the MD5 hash in the presigned URL. The MD5 hash of the uploaded content must be the same as the MD5 hash calculated by the OSS SDK. Otherwise, the PUT request fails. To verify the MD5 hash of the uploaded content, add the Content-MD5 header to the request.

Implementation methods

• Examples of signed URLs

  https://examplebucket.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=nz2pc56s936****&Expires=1141889120&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv****

  If you want to use temporary access credentials obtained from Security Token Service (STS) to generate a signed URL, you must include the security-token parameter in the signature.

  https://examplebucket.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=nz2pc56s936****&Expires=1141889120&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv****&security-token=CAISowJ1q6Ft5B2yfSjIr5bgIOz31blR9oWmWBfCs3kDR/xm3Imc1zz2IHxMdHJsCeAcs/Q0lGFR5/sflqJIRoReREvCUcZr8szfWcsZos2T1fau5Jko1be0ewHKeQKZsebWZ+LmNpy/Ht6md1HDkAJq3LL+bk/Mdle5MJqP+/kFC9MMRVuAcCZhDtVbLRcYgq18D3bKMuu3ORPHm3fZCFES2jBxkmRi86+ysIP+phPVlw/90fRH5dazcJW0Zsx0OJo6Wcq+3+FqM6DQlTNM6hwNtoUO1fYUommb54nDXwQIvUjfbtC5qIM/cFVLAYEhALNBofTGkvl1h/fejYyfyWwWYbkFCHiPFNr9kJCUSbr4a4sjF6zyPnPWycyCLYXleLzhxPWd/2kagAGaXG69BqwYNvrKKI3W8weP3bNc1wQDMXQfiHpFCRG6lYhh3iXFtpwH90A3sTlxzRGvi8+9p63JwrluOHWs+Fj6S6s0cOhKvKRWYE8UuWeXIvv4l6DAGwHDE8BLjLC11f5prUJgI2wb+3hwuBod32Jx+us/1p996Glao725orcb****

  You can add an IP address, a CIDR block, or a virtual private cloud (VPC) ID to the signed URL to prevent unauthorized terminals from accessing the shared OSS resources.

  https://examplebucket.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?&OSSAccessKeyId=44CF9590006BF252F707&Expires=1475462111&Signature=OjxkTUbT6rXCZcW8QhvlrXQr8vsP80EFdo6oG5qsBx****&x-oss-ac-subnet-mask=32

• Parameters

  Parameter	Type	Required	Description
  OSSAccessKeyId	STRING	Yes	The AccessKey ID used in the signed URL.
  Expires	NUMERIC	Yes	The UNIX timestamp, which is the number of seconds that have elapsed since 00:00:00 Thursday, January 1, 1970 at UTC. If the time when OSS receives the request that contains the URL is later than the value of this parameter that is included in the signature, a request timeout error is returned. For example, if the current time is 1141889060 and you want to create a URL that is valid within 60 seconds, you must set this parameter to 1141889120. Note For security reasons, the default validity period of URLs generated in the OSS console is 3,600 seconds and the maximum validity period is 32,400 seconds. For more information about how to change the validity period of a URL, see Share objects.
  Signature	STRING	Yes	The signature information that you want to add to the URL. The following code provides an example on the valid format: Signature = urlencode(base64(hmac-sha1(AccessKeySecret, VERB + "\n" + CONTENT-MD5 + "\n" + CONTENT-TYPE + "\n" + EXPIRES + "\n" + CanonicalizedOSSHeaders + CanonicalizedResource))) In OSS, the algorithm used to calculate the signature added to a URL is similar to that used to calculate the signature added to the Authorization header of a request. When you calculate the signature string to be added to a URL, the Content-Type, Content-MD5, and CanonicalizedOSSHeaders headers are the same as those used to calculate the signature that you add to the Authorization header. However, you must replace the Date header with Expire in the signature string. You can include the Date header in the request. For more information about the headers, see Include signatures in the Authorization header. You must encode a URL when you add a signature to the URL. If the value of Signature, Expires, or OSSAccessKeyId is imported multiple times, the first imported value is used. If a request contains a signed URL, OSS first checks whether the time when the request is received is later than the value of Expires, and then verifies the signature.
  security-token	STRING	No	The security token that is obtained from STS. You must configure this parameter only if you use temporary access credentials to sign the URL. Note For more information about how to configure STS, see Use temporary credentials provided by STS to access OSS. You can call the AssumeRole operation or use STS SDKs for various programming languages to obtain a temporary access credential. Temporary access credentials contain a security token and a temporary AccessKey pair. The AccessKey pair consists of an AccessKey ID and an AccessKey secret.
  x-oss-ac-source-ip	STRING	No	The specified IP address or CIDR block. This parameter must be used together with x-oss-ac-subnet-mask that specifies the subnet mask.
  x-oss-ac-subnet-mask	NUMERIC	No	The number of 1's in the subnet mask. If this parameter is contained in the signed URL, OSS performs the AND operation based on the IP address from which the request is sent and the subnet mask. The result of the operation is used for signature verification. If the value of the parameter is maliciously modified, the signature cannot pass the verification.
  x-oss-ac-vpc-id	STRING	No	The VPC ID. This parameter is used to determine whether the request is sent over the specified VPC. If the request is sent over the specified VPC, OSS verifies the VPC ID and the IP address or CIDR block from which the request is sent.
  x-oss-ac-forward-allow	BOOLEAN	No	Specifies whether the request can be forwarded. If the x-oss-ac-forward-allow and X-Forwarded-For parameters are included in the request, the value of the X-Forwarded-For parameter is used to verify the signature. Multiple IP addresses may be specified in the X-Forwarded-For parameter. Default value: false. Valid values: true: The request can be forwarded. Important This may cause the request header to be tampered with. false: The request cannot be forwarded.

• Sample Python code used to generate a signature
  • Example 1 (Only required parameters)

    import base64
    import hmac
    import hashlib
    import urllib
    h = hmac.new("accesskey",
                 "GET\n\n\n1141889120\n/examplebucket/oss-api.pdf",
                 hashlib.sha1)
    urllib.quote(base64.encodestring(h.digest()).strip())

  • Example 2 (Including optional parameters)
    • Before you sign a URL, you must sort the optional parameters in alphabetical order. You can leave optional parameters empty based on your business requirements.
    • If you want to specify an IP address from which the access request is sent, you can specify the x-oss-ac-source-ip and x-oss-ac-subnet-mask parameters. Examples: x-oss-ac-source-ip=127.0.0.1 and x-oss-ac-subnet-mask=32.

    import base64
    import hmac
    import hashlib
    import urllib
    h = hmac.new(accesskey,
                 "GET\n\n\n1141889120\n%2Fexamplebucket%2Foss-api.pdf?\
                 &x-oss-ac-forward-allow=true\
                 &x-oss-ac-source-ip=127.0.0.1\
                 &x-oss-ac-subnet-mask=32\
                 &x-oss-signature-version=OSS2",
                 hashlib.sha256)
    Signature = base64.encodestring(h.digest()).strip()

SDKs

The following table describes the implementation methods to add signatures to a URL by using OSS SDKs for programming languages and provides links to sample code of uploading or downloading objects by using signed URLs.

Error codes