Include a V4 signature in the Authorization header (recommended) -

When initiating requests to OSS, you need to include an Authorization request header containing a V4 signature to ensure successful authentication. Please prioritize the use of the OSS-provided SDK to initiate requests, as the SDK already integrates the sophisticated V4 signature algorithm. Only when the SDK cannot be used should you refer to this documentation to manually implement the V4 signature algorithm.

Use OSS SDKs to automatically implement V4 signatures

If you need to implement the V4 signature algorithm, we recommend that you refer to the V4 signature implementation in OSS SDKs.

SDK	Implementation
Java	OSSV4Signer.java
Python	v4.py
Go	v4.go
JavaScript	client.js
PHP	SignerV4.php
C#	SignerV4.cs
Android	OSSV4Signer.java
iOS	OSSV4Signer.m
C++	SignerV4.cc
C	oss_auth.c

Authorization request headers

When initiating a request to OSS, you need to implement the signature in the Authorization header to verify the request.

Below is the syntax of the Authorization header:

Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<SignDate>/<SignRegion>/oss/aliyun_v4_request, AdditionalHeaders=<AdditionalHeadersVal>, Signature=<SignatureVal>

Below is the description of the Authorization header:

Component	Description
OSS4-HMAC-SHA256	Specifies the algorithm used to calculate the signature. This string specifies the signature version and the signing algorithm (HMAC-SHA256). The value of OSS4-HMAC-SHA256 is required when V4 signatures are used for authentication.
Credential	Specifies the AccessKey ID and scope, which includes the date, region, and cloud service used to calculate the signature. This field is required when when V4 signatures are used for authentication. Below is the syntax: `<AccessKeyId>/<SignDate>/<SignRegion>/oss/aliyun_v4_request` Where: `AccessKeyId`: Your AccessKey ID, which is a unique identifier used to verify the identity of the requester. `SignDate`: The signature date in the YYYYMMDD format. `SignRegion`: The region ID used for the request. Example: cn-hangzhou. `oss`: A fixed string that identifies the service being requested as Alibaba Cloud Object Storage Service (OSS). `aliyun_v4_request`: A fixed string that specifies the signature version as V4.
AdditionalHeaders	Specify the optional request headers that are included in signature calculation (you do not need to specify the required headers that must be included in signature calculation). This field contains only lowercase header names, sorted in lexicographic order and separated by semicolons (;). The sample is as follows: `content-disposition;content-length`
Signature	The calculated signature. The field is required when V4 signatures are used for authentication. The following sample code provides an example of a 256-bit signature value represented by 64 lowercase hexadecimal digits: `3938**********************************dcdc`

Signature calculation

After receiving a request, OSS calculates the signature and compares it with the one in the Authorization request header. If they match, the request succeeds. Otherwise, the request fails.

Signature calculation process

The following figure shows the signature calculation process:

The signature calculation process consists of the following three steps:

Construct a canonicalized request: Format the request according to OSS signature specifications to generate a canonicalized request.
Construct a string-to-sign: Concatenate the canonicalized request to derive the string-to-sign.
Calculate the signature: Perform multiple hash operations on the AccessKey Secret to generate a derived key, and then use the derived key to calculate the string-to-sign to obtain the final signature. By performing multi-step HMAC-SHA256 operations on the AccessKey Secret, a derived key will be generated to calculate the HMAC-SHA256 hash of the string-to-sign, resulting in the final signature.

1. Construct a canonicalized request

Below is the syntax of a canonicalized request:

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

The following table describes the parameters in a canonicalized request:

Parameter	Description
HTTP Verb	The HTTP request method, including PUT, GET, POST, HEAD, DELETE, and OPTIONS.
Canonical URI	URI-encoded resource path. The resource path does not include the query string, and encoding for forward slashes (`/`) is not required. If the request target is the OSS, the resource path is `/`, and the URI-encoded resource path is `UriEncode("/")`. If the request target is a bucket, the resource path is `/examplebucket/`, and the URI-encoded resource path is `UriEncode("/examplebucket/")`. If the request target is an object in a bucket, the resource path is `/examplebucket/exampleobject`, and the URI-encoded resource path is `UriEncode("/examplebucket/exampleobject")`.
Canonical Query String	URI-encoded query parameters sorted in lexicographical order. If query parameters include both parameter names and values, URI-encode the name and value of each parameter separately and sort the parameters in lexicographical order based on their encoded names. Note that sorting is performed after encoding. Use `=` to connect the encoded name and value, and use `&` to concatenate different parameters. Query parameters: `prefix=somePrefix&marker=someMarker&max-keys=20` Canonicalized query parameters: `UriEncode("marker")+"="+UriEncode("someMarker")+"&"+UriEncode("max-keys")+"="+UriEncode("20")+"&"+UriEncode("prefix")+"="+UriEncode("somePrefix")` If the query parameter contains only the parameter name, perform URI encoding on the parameter name and construct the formatted query in the `parameter name=` format. Query parameter: `?acl` Canonicalized query parameter: `UriEncode("acl") + "=" + ""` If there are no query parameters, i.e., the request URI does not contain a `?`, the canonicalized query string is set to an empty string (`""`).
Canonical Headers	The list of request headers. Request headers fall into the following three categories: Headers that must exist in the request and included in signature calculation: `x-oss-content-sha256`: only UNSIGNED-PAYLOAD is supported. Headers that must be included in signature calculation if they exist in the request: `Content-Type` `Content-MD5` `x-oss-*`: Other request headers that start with `x-oss-`. For example, when accessing via the STS AK, the SecurityToken is described through `x-oss-security-token:security-token`. For example, the request time is described through `x-oss-date`, and the syntax must be the ISO8601 standard time format, such as `20231203T121212Z`. Optional request headers specified in `AdditionalHeaders`. The syntax is as follows: `Lowercase(<HeaderName1>) + ":" + Trim(<value>) + "\n" Lowercase(<HeaderName2>) + ":" + Trim(<value>) + "\n" ... Lowercase(<HeaderNameN>) + ":" + Trim(<value>) + "\n"` The following sample code provides an example: `content-disposition:attachment content-length:3 content-md5:ICy5YqxZB1uWSwcVLSNLcA== content-type:text/plain x-oss-content-sha256:UNSIGNED-PAYLOAD x-oss-date:20250328T101048Z`
Additional Headers	Specifies the optional request headers that are included in signature calculation (you do not need to specify the required headers that must included in signature calculation). This field contains only lowercase header names, sorted in lexicographic order and separated by semicolons (;), consistent with `AdditionalHeaders`. Specify the optional headers that included in signature calculation (excluding mandatory headers), only lowercase header names are included and sorted lexicographically. They are separated by semicolons (`;`) and consistent with `AdditionalHeaders`. The following sample code provides an example: `content-disposition;content-length`
Hashed PayLoad	The hexadecimal representation of the SHA256 hash value of the request payload. Only the value `UNSIGNED-PAYLOAD` is supported.

2. Construct a string-to-sign

The syntax of the string-to-sign is as follows:

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

The following table describes the parameters in the string-to-sign:

Parameter	Description
OSS4-HMAC-SHA256	The hash algorithm of the signature, the value must be `OSS4-HMAC-SHA256`.
TimeStamp	The current UTC time, the syntax of which must be ISO8601, such as `20250320T083322Z`.
Scope	The parameter set to get/retrieve the derived key. This parameter set specifies the date, region and service. Therefore, the signature calculated using the derived key is valid only for the specified date, region, and service. The syntax is as follows: `<SignDate>/<SignRegion>/oss/aliyun_v4_request` The description is as follows: `SignDate`: The `YYYYMMDD` formatted date which is included in the signature. `SignRegion`: The region ID used for the signature, such as `cn-hangzhou`. `oss`: The service name that is included in the signature, fixed as `oss`. `aliyun_v4_request`: The version that is included in the signature, fixed as `aliyun_v4_request`.
CanonicalRequest	The constructed canonicalized request.

3. Calculate a signature

Calculating a signature involves the following two steps:

Calculate the SigningKey.
```
DateKey = HMAC-SHA256("aliyun_v4" + SK, Date);
DateRegionKey = HMAC-SHA256(DateKey, Region);
DateRegionServiceKey = HMAC-SHA256(DateRegionKey, "oss");
SigningKey = HMAC-SHA256(DateRegionServiceKey, "aliyun_v4_request");
```
- SK: The AccessKey Secret that is included in the signature.
- Date: The YYYYMMDD formatted date included in the signature, which must be consistent with the SignDate in the string-to-sign.
- Region: The region ID used for the signature, such as cn-hangzhou, which must be consistent with the SignRegion in the string-to-sign.
Calculate the Signature using the SigningKey and the string-to-sign.
```
Signature = HEX(HMAC-SHA256(SigningKey, StringToSign))
```

Signature calculation example

The following example shows how to calculate a signature by calling a PutObject operation.

Parameters for signature calculation

Parameter	Value
AccessKeyId	LTAI****************
AccessKeySecret	yourAccessKeySecret
Timestamp	20250411T064124Z
Bucket	examplebucket
Object	exampleobject
Region	cn-hangzhou

Example of signature calculation

Construct a canonicalized request.

PUT
/examplebucket/exampleobject

content-disposition:attachment
content-length:3
content-md5:ICy5YqxZB1uWSwcVLSNLcA==
content-type:text/plain
x-oss-content-sha256:UNSIGNED-PAYLOAD
x-oss-date:20250411T064124Z

content-disposition;content-length
UNSIGNED-PAYLOAD

Construct a string-to-sign.

OSS4-HMAC-SHA256
20250411T064124Z
20250411/cn-hangzhou/oss/aliyun_v4_request
c46d96390bdbc2d739ac9363293ae9d710b14e48081fcb22cd8ad54b63136eca

Calculate the signature.
1. Calculate the SigningKey.
  Note
  For ease of readability, the following SigningKey is displayed in hexadecimal format.
```
3543b7686e65eda71e5e5ca19d548d78423c37e8ddba4dc9d83f90228b457c76
```
2. Calculate the Signature.
```
053edbf550ebd239b32a9cdfd93b0b2b3f2d223083aa61f75e9ac16856d61f23
```