Include a V1 signature in a URL

SDK signature implementation

OSS SDKs automatically implement V1 signatures. You do not need to handle signatures when you use an OSS SDK. To understand the signature implementation for a specific language, see the SDK's source code. The following table lists the files that implement the signature for each SDK.

Usage notes

• If you use a signed URL, the authorized data is exposed on the internet until the URL expires. Evaluate the risks before you use this method.

• OSS does not support including signatures in both the URL and the request header at the same time.

• You can generate a presigned URL for a PUT operation to ensure that the correct content is uploaded. When an SDK presigns a request, it calculates the MD5 checksum of the request body and includes the checksum in the presigned URL. The user must upload content with an MD5 checksum that matches the one in the presigned URL. Otherwise, the operation fails. To validate the MD5, add the Content-MD5 header to the request.

Signature implementation

• Example signature

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

  If you use a Security Token Service (STS) user to construct a signed URL, you must include the security-token parameter.

  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 a specific IP address, IP address range, or VPC ID to the signed URL to prevent unauthorized clients from accessing OSS resources.

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

• Parameters

  Name	Type	Required	Description
  OSSAccessKeyId	String	Yes	The AccessKey ID used in the URL signature.
  Expires	Number	Yes	The expiration time of the URL in format. Unix time is the number of seconds that have elapsed since 00:00:00 UTC on January 1, 1970. If OSS receives the request after the expiration time, it returns a timeout error code. For example, if the current time is 1141889060 and you want to create a URL that expires in 60 seconds, set Expires to 1141889120. Note For security, the default validity period of a URL in the OSS console is 3,600 seconds. The maximum validity period is 32,400 seconds. For more information about how to change the URL expiration time, see Use file URLs.
  Signature	String	Yes	The signature information. The format is as follows: Signature = urlencode(base64(hmac-sha1(AccessKeySecret, VERB + "\n" + CONTENT-MD5 + "\n" + CONTENT-TYPE + "\n" + EXPIRES + "\n" + CanonicalizedOSSHeaders + CanonicalizedResource))) The algorithm for signing in a URL is similar to the algorithm for including a signature in the header for all supported OSS requests and header parameters. 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 parameter with the Expires parameter in the signature string. You can include the Date header in the request, but you do not need to include it in the signature string. You must URL-encode the signature when you include it in a URL. If Signature, Expires, or OSSAccessKeyId are passed multiple times in the URL, the first value is used. When a signed URL is used, OSS first checks if the request time is after the Expires time, and then validates the signature.
  security-token	String	No	The security token. Set this parameter only when you use an STS user to construct the signed URL. Note For more information about how to set up the STS service, see Use temporary access credentials from STS to access OSS. You can obtain temporary access credentials by calling the STS AssumeRole API operation or using the STS SDKs for different languages. Temporary access credentials include a temporary AccessKey pair (AccessKey ID and AccessKey secret) and a security token (SecurityToken).
  x-oss-ac-source-ip	String	No	Specifies the IP address or IP address range. Important This parameter is only used when you generate the signature. You do not need to include this parameter in the URL. If you add an IP address or IP address range when you generate the signature, you must also pass the x-oss-ac-subnet-mask parameter to specify the subnet mask.
  x-oss-ac-subnet-mask	Number	No	The number of 1s in the subnet mask. If the request includes this parameter, OSS performs a bitwise AND operation on the actual request IP address and the subnet mask. The result is used to verify the signature. If this parameter is tampered with, the signature validation fails.
  x-oss-ac-vpc-id	String	No	Specifies the VPC ID. After you specify this parameter, OSS determines whether the request originates from the corresponding VPC ID. If the request originates from the specified VPC ID and this parameter is set, OSS validates both the VPC ID and the source IP address or IP address range.
  x-oss-ac-forward-allow	Boolean	No	Specifies whether to allow forwarded requests. If OSS detects this field and the request contains X-Forwarded-For, which may contain multiple IP addresses, OSS uses the value of X-Forwarded-For to validate the signature. The following values are valid: true: Allows forwarded requests. Important Setting this to true creates a risk that the request header could be tampered with or hijacked. false (default): Does not allow forwarded requests.

• Python sample code for signing (including only required parameters)

  import base64
  import hmac
  import hashlib
  from urllib.parse import quote
  
  access_key_secret = "yourAccessKeySecret"
  string_to_sign = "GET\n\n\n1141889120\n/examplebucket/oss-api.pdf"
  
  h = hmac.new(
      access_key_secret.encode('utf-8'),
      string_to_sign.encode('utf-8'),
      hashlib.sha1
  )
  
  signature = quote(base64.b64encode(h.digest()).decode('utf-8'))
  print(signature)

Error codes