Object Storage Service:Include a V1 signature in a URL

Use OSS SDKs to automatically implement V1 signatures

OSS SDKs support the automatic implementation of V1 signatures. When you use OSS SDKs, you do not need to add signatures to requests. For more information about the signature implementation for a specific programming language, see the sample code of OSS SDK for that programming language. The following table provides references to the sample code used to sign requests by using the V1 signature algorithm when you use OSS SDKs for different programming languages.

Usage notes

• If you use a signed URL to share data, the data can be accessed by all Internet users that have the URL within the URL validity period. We recommend that you assess data 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 generate a signed URL for a PUT request to check whether the content that you want to upload is valid. If you use an OSS SDK to generate a signed URL for a request, the OSS SDK calculates the MD5 hash of the request body and includes the MD5 hash in the signed 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

  https://examplebucket.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=nz2p***********&Expires=1141889120&Signature=****Pxyb****mGa%****272YEAiv****

  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 URL.

  https://examplebucket.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=nz2p***********&Expires=1141889120&Signature=****Pxyb****mGa%****272YEAiv****&security-token=CAIS****q6Ft5B2yfSjIr****Oz31blR9oWmWBf****DR/xm3Imc****IHxMdHJsCeAcs/Q0lGFR5/sflqJIR****EvCUcZr8szfWcsZos2****u5Jko1be0ewHKeQKZsebWZ+LmNpy/Ht6md1HDkAJq3LL+bk/Mdle5MJqP+/kFC9MMRVuAcCZhDtVbLRcYgq18D3bKMuu3ORPHm3fZCFES2jBxkmRi86+ysIP+phPVlw/90fRH5dazcJW0Zsx0OJo6Wcq+3+FqM6DQlTNM6hwNtoUO1fYUommb54nDXwQIvUjfbtC5qIM/cFVLAYEhAL****TGkvl1h/fejYyfyW****kFCHiPF****JCUSbr4a4sjF6zyPnPWycyCLYXleLzhxPWd/2kagAGaXG69BqwYNvrKKI3W8****bNc1wQDMXQfiHpFCRG6lYhh3****pwH90A3sTlxzRGvi8+****JwrluOHWs+Fj6S6s0cOhKvKRWYE8UuWeXIvv4l6DAGwH****LjLC11f5prUJ****b+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=44CF****************&Expires=1475462111&Signature=77Dv****************&x-oss-ac-subnet-mask=32

• The following table describes the parameters in the preceding URL.

  Parameter	Type	Required	Description
  OSSAccessKeyId	String	Yes	The AccessKey ID used in the signed URL.
  Expires	Numeric	Yes	The time when the signed URL expires. The timestamp follows the UNIX time format. It is the number of seconds that have elapsed since 00:00:00 Thursday, January 1, 1970. If the time when OSS receives the request that contains the URL is later than the value of this parameter, a request timeout error is returned. For example, if the current time is 1141889060 and you want to create a URL that is valid for 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 modify the validity period of a URL, see Use object URLs.
  Signature	String	Yes	The signature information that you want to add to the URL. You must provide signature information in the following 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, headers defined in signature V1 such as CONTENT-TYPE, CONTENT-MD5, and CanonicalizedOSSHeaders 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, but do not need to include it in the signature string. You must encode a URL when you add a signature to the URL. If you specify a value for Signature, Expires, or OSSAccessKeyId multiple times, the first value is used. If you use a signed URL to request a resource, 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 access credentials provided by STS to access OSS. You can call the AssumeRole operation or use STS SDKs for various programming languages to obtain temporary access credentials. Temporary access credentials contain a security token and a temporary AccessKey pair. An AccessKey pair consists of an AccessKey ID and an AccessKey secret.
  x-oss-ac-source-ip	String	No	The IP address or CIDR block. Important This parameter is used only when the signature is generated. You do not need to include this parameter in the URL. 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 digit 1 in the subnet mask. If this parameter is included 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 to verify the signature of the URL. If this parameter is tampered with, the signature verification fails.
  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 to allow request forwarding. If OSS detects this field and the request contains X-Forwarded-For (possibly with multiple IP addresses), OSS uses the value of X-Forwarded-For for signature verification. Valid values: true Important If you set the parameter to true, the request header may be tampered with. false (default)

• Python sample code for signing (including 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())

Error codes