All Products
Search

This Product

    Object Storage Service:Include a V4 signature in a URL (recommended)

    Document Center

    Object Storage Service:Include a V4 signature in a URL (recommended)

    Last Updated:Apr 09, 2024

    In addition to using the HTTP Authorization header for providing authentication information, you can use query string parameters to authenticate requests when you want to express a request entirely in a URL. This way, you can grant users temporary access permissions on the specified Object Storage Service (OSS) resources without exposing your access credentials. This topic describes how to include a V4 signature in a URL.

    Use OSS SDKs to automatically implement V4 signatures

    OSS SDKs support the automatic implementation of V4 signatures. We recommend that you use OSS SDKs to initiate requests. This eliminates the need to manually calculate signatures. For more information about how to sign requests by using the V4 signature algorithm when you use OSS SDKs for different programming languages, see the sample code of OSS SDKs. The following table provides references to the sample code that is used to sign requests initiated by using OSS SDKs for different programming languages.

    OSS SDK

    Sample code

    Java

    OSSV4Signer.java

    PHP

    SignerV4.php

    Node.js

    signatureUrlV4.js

    Browser.js

    Python

    auth.py

    Go

    v4.go

    C++

    SignerV4.cc

    C

    oss_auth.c

    URL signing

    • Example

      https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject?x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=<AccessKeyId>/20231203/cn-hangzhou/oss/aliyun_v4_request&x-oss-date=20231203T121212Z&x-oss-expires=86400&x-oss-additional-headers=host&x-oss-signature=<signature-to-be-calculated>

      For readability, the fields in the x-oss-credential parameter in the preceding URL are separated by forward slashes (/). When you initiate a request, URI-encode the forward slashes (/) in the URL to convert them into %2F. Example:

      &x-oss-credential=<AccessKeyId>%2F20231203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request

    • Query string parameters

      Parameter

      Type

      Required

      Example

      Description

      x-oss-signature-version

      String

      Yes

      OSS4-HMAC-SHA256

      The version and algorithm of the signature. Set the value to OSS4-HMAC-SHA256.

      x-oss-credential

      String

      Yes

      LTAI5t7h6SgiLSganP2m****/20231203/cn-hangzhou/oss/aliyun_v4_request

      The credentials that you can use to calculate the signature. Format:

      <AccessKeyId>/<date>/<region>/oss/aliyun_v4_request

      • AccessKeyId: the AccessKey ID in the AccessKey pair.

      • date: the date when the request was initiated.

      • region: the region in which the requested resource resides.

      • oss: the name of the requested service. Valid value: oss.

      • aliyun_v4_request: the description of the signature version in the request. Valid value: aliyun_v4_request.

      x-oss-date

      String

      Yes

      20231203T121212Z

      The time when the URL was signed. The time follows the ISO 8601 standard. To avoid time differences, an offset of 15 minutes after the URL was signed is allowed.

      Note

      The time is used as the timestamp for the string to sign. The value must be the same as that of the date field in the derived signing key.

      x-oss-expires

      Integer

      Yes

      3600

      The validity period of the signed URL. Unit: seconds. Minimum value: 1. Maximum value: 604800.

      x-oss-additional-headers

      String

      No

      host

      The headers to be added to calculate the signature. We recommend that you sign all request headers that you want to include in your request.

      The following items describe the requirements for constructing the parameter:

      • All headers in the x-oss-additional-headers parameter must be in lowercase letters.

      • All headers in the x-oss-additional-headers parameter must be sorted in alphabetical order.

      • All headers in an array are separated by semicolons (;) to obtain a string.

      x-oss-signature

      String

      Yes

      2c6c9f10d8950fb150290ef6f42570e33cd45d6a57ec7887de75fa2ec45b4c72

      The description of the signature verification. The x-oss-signature parameter is not included in the signature calculation.

      x-oss-security-token

      String

      No

      CAISowJ1q6Ft5B2yfSjIr5bgIOz31blR****

      The security token issued by Security Token Service (STS). This parameter is required only when you use an STS user to construct a signature for the URL.

    Signature calculation process

    image

    The method used to calculate a signature for a URL is similar to the method used to calculate a signature for the Authorization header. The following items describe the differences between the two methods:

    • The x-oss-content-sha256 header that describes a payload hash is not used to calculate a signature for a URL. When you create a signed URL, you cannot evaluate the payload content. Instead, UNSIGNED-PAYLOAD is used.

    • The headers to be added to calculate the signature do not contain Content-Type and Content-MD5.

    • If a key in the query string parameters of a signed URL is the same as a header to be signed but their values are different, an error is reported. If a key has multiple values, all values of the key are compared at the same time. If the values are inconsistent, an error is reported.

    • If you use the access credentials obtained from STS to access OSS resources in a signed URL, you must add the x-oss-security-token parameter to the query string of the URL.

    • The x-oss-signature parameter in the query string is not included in the signature calculation.

    Step 1: Create a canonical request

    Convert the content of your request to the canonical format.

    Format

    HTTP Verb + "\n" +
Canonical URI + "\n" +
Canonical Query String + "\n" +
Canonical Headers + "\n" +
Additional Headers + "\n" +
Hashed PayLoad

    The following table describes the preceding parameters.

    Parameter

    Type

    Required

    Example

    Description

    HTTP Verb

    Enumeration

    Yes

    PUT

    The method of the HTTP request, such as PUT, GET, POST, HEAD, DELETE, or OPTIONS.

    Canonical URI

    String

    Yes

    /examplebucket/exampleobject

    A URI-encoded string. Do not encode the forward slash (/) in the absolute path.

    • The URI starts with a forward slash (/) that follows the domain name up to the end of the string if query string parameters are not included.

    • The URI starts with a forward slash (/) that follows the domain name and ends with a question mark (?) if query string parameters are included.

    The following items describe how to specify a canonical URI based on the resources included in the request URI:

    • If the request URI contains both a bucket name and an object name, the canonical URI is in the following format:

      /examplebucket/exampleobject.

    • If the requested URI contains only a bucket name, the canonical URI is in the following format: /examplebucket/.

    • If the requested URI contains only an object name, the canonical URI is set to /.

    Canonical Query String

    String

    Yes

    UriEncode("marker") + "=" + UriEncode("someMarker") + "&" + UriEncode("max-keys") + "=" + UriEncode("20") + "&" + UriEncode("prefix") + "=" + UriEncode("somePrefix")

    The URI-encoded query string parameters. You need to URI-encode each key and value individually.

    • Sort the parameters in the canonical query string alphabetically by key name. The sorting occurs after encoding. If identical keys exist, sort the keys in chronological order based on the time when they were added.

    • If a key does not have a value, add only the key.

    • If a request does not include a query string, set the canonical query string to an empty string (""). You must add a line feed at the end.

    • If a key in the query string parameters of a signed URL is the same as a header to be signed but their values are different, an error is reported. If a key has multiple values, all values of the key are compared at the same time. If the values are inconsistent, an error is reported.

    Canonical Headers

    String

    Yes

    host:cname.com
x-oss-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-oss-date:20231203T121212Z

    A string obtained by converting the list of request headers to the canonical format. Add a line feed to the end of the string.

    • A header key and value are separated by a colon (:), and headers are separated by a line feed.

    • Header keys must be in lowercase letters and sorted in alphabetical order. Leading or trailing spaces in the header values must be trimmed.

    • Header keys are sorted in alphabetical order.

    • The request time is specified by the x-oss-date header. The time follows the ISO 8601 standard and is displayed in UTC. Example: 20231203T121212Z.

    • The x-oss-content-sha256 header that describes a payload hash is not used to calculate a signature for a URL. When you create a signed URL, you cannot evaluate the payload content. Instead, UNSIGNED-PAYLOAD is used.

    Canonical Headers must include the following headers:

    • The headers specified by Additional Headers and used for signature calculation

    • The headers that must be added to Canonical Headers if they are in the request, including headers prefixed with x-oss-*

    Additional Headers

    String

    Yes

    content-length;host

    The headers to be added to calculate the signature. All headers must be in lowercase and sorted in alphabetical order.

    Hashed PayLoad

    String

    Yes

    UNSIGNED-PAYLOAD

    Valid value: UNSIGNED-PAYLOAD.

    Example

    "GET" | "PUT" | ... + "\n" +
UriEncode(<Resource>) + "\n" +
UriEncode(<QueryParam1>) + "=" + UriEncode(<Value>) + "&" + UriEncode(<QueryParam2>) + "\n" +
Lowercase(<HeaderName1>) + ":" + Trim(<value>) + "\n" + Lowercase(<HeaderName2>) + ":" + Trim(<value>) + "\n" + "\n"
Lowercase(<AdditionalHeaderName1>) + ";" + Lowercase(<AdditionalHeaderName2>) + "\n" +
UNSIGNED-PAYLOAD

    Step 2: Create a string to sign

    Concatenate the following strings to create a string to sign.

    • Format

      "OSS4-HMAC-SHA256" + "\n" +
TimeStamp + "\n" +
Scope + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

      The following table describes the preceding parameters.

      Parameter

      Type

      Required

      Example

      Description

      OSS4-HMAC-SHA256

      Enumeration

      Yes

      OSS4-HMAC-SHA25

      The algorithm used to create the hash of the canonical request. Valid value: OSS4-HMAC-SHA256.

      TimeStamp

      String

      Yes

      20231203T121212Z

      The current UTC time. The time must follow the ISO 8601 standard.

      Scope

      String

      Yes

      20231203/cn-hangzhou/oss/aliyun_v4_request

      The scope information. This restricts the resulting signature to the specified region and service. Format:

      <SignDate>/<Region>/oss/aliyun_v4_request

      • SignDate: the date when the request is initiated.

      • Region: the region in which the requested resource resides.

      • oss: the name of the requested service. Valid value: oss.

      • aliyun_v4_request: the description of the signature version in the request. Valid value: aliyun_v4_request.

      CanonicalRequest

      String

      Yes

      PUT

      /examplebucket/exampleobject

      x-oss-additional-headers=host&x-oss-credential=accesskeyid%2F20231203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-date=20231203T121212Z&x-oss-expires=86400&x-oss-signature-version=OSS4-HMAC-SHA256

      host:examplebucket.oss-cn-hangzhou.aliyuncs.com

      x-oss-meta-author:alice

      x-oss-meta-magic:abracadabra

      host

      UNSIGNED-PAYLOAD

      The string constructed in Step 1.

    • Example

      "OSS4-HMAC-SHA256" + "\n" +
FormatISO8601 + "\n" +
20231203/cn-hangzhou/oss/aliyun_v4_request + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

    Step 3: Calculate the signature

    After you derive the signing key, calculate the signature by performing a keyed hash operation on the string to sign. Use the derived signing key as the hash key for this operation.

    1. Calculate the signing key. 

      HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("aliyun_v4" + SK, Date), Region), "oss"), "aliyun_v4_request");

    2. Calculate the signature. 

      HEX(HMAC-SHA256(SigningKey, StringToSign))

    Signature calculation example

    In this example, a signed URL is created. You can share the signed URL to third-party users to upload data to OSS. The following section shows how to include a V4 signature in the URL.

    • Parameters

      Parameter

      Example

      AccessKeyId

      accesskeyid

      AccessKeySecret

      accesskeysecret

      Timestamp

      20231203T121212Z

      Bucket

      examplebucket

      Object

      exampleobject

      Region

      cn-hangzhou

    • PutObject

      https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject?x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=accesskeyid/20231203/cn-hangzhou/oss/aliyun_v4_request&x-oss-date=20231203T121212Z&x-oss-expires=86400&x-oss-additional-headers=host&x-oss-signature=<signature-to-be-calculated>
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
x-oss-meta-author: alice
x-oss-meta-magic: abracadabra

    To include a V4 signature in a URL, perform the following steps:

    1. Create a canonical request. 

      PUT
/examplebucket/exampleobject
x-oss-additional-headers=host&x-oss-credential=accesskeyid%2F20231203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-date=20231203T121212Z&x-oss-expires=86400&x-oss-signature-version=OSS4-HMAC-SHA256
host:examplebucket.oss-cn-hangzhou.aliyuncs.com
x-oss-meta-author:alice
x-oss-meta-magic:abracadabra

host
UNSIGNED-PAYLOAD

    2. Create a string to sign. 

      OSS4-HMAC-SHA256
20231203T121212Z
20231203/cn-hangzhou/oss/aliyun_v4_request
672d815902f04dd8aa90a558931f471cc7269d08a122a5e9028022d9f723332c

    3. Calculate the signature.

      1. Calculate the signing key.

        Note

        For readability, the following example shows the Base64-encoded value of the signing key. 

        WVjaYR8lCj9YC5PUS2RSZQANYbuh9DhMFxjU1NtZKfc=

      2. Calculate the signature. 

        2c6c9f10d8950fb150290ef6f42570e33cd45d6a57ec7887de75fa2ec45b4c72

    4. Add the signature to the URL. 

      https://examplebucket.oss-cn-hangzhou.aliyuncs.com?x-oss-additional-headers=host&x-oss-credential=accesskeyid%2F20231203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-date=20231203T121212Z&x-oss-expires=86400&x-oss-signature=2c6c9f10d8950fb150290ef6f42570e33cd45d6a57ec7887de75fa2ec45b4c72&x-oss-signature-version=OSS4-HMAC-SHA256
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
x-oss-meta-author: alice
x-oss-meta-magic: abracadabra