POST V1 signature-Object Storage Service(OSS)-阿里云帮助中心

To secure uploads that use the PostObject operation, OSS requires a signature in each upload request. In a POST V1 signature, the signature is calculated by using an AccessKey secret to sign a set of request parameters, such as the upload policy and its expiration time. The application server generates a signature and provides it to the client along with the policy. The client then uses this information to construct the upload request. When OSS receives the request, it verifies the validity of the signature. OSS accepts requests with a valid signature and rejects those with an invalid one.

Important

OSS supports the more secure V4 signature algorithm. We recommend using V4 signature for new integrations.

POST signatures

HTTP POST requests support the V1 signature algorithm. The form and policy play key roles in ensuring the security and compliance of upload requests.

Form fields

A form is a collection of fields in a POST request that transmit the object and its metadata. The following table describes the form fields that are specific to POST V1 signatures. For information about other common form fields, see PostObject form elements.

Field

Type

Description

OSSAccessKeyId

String

The AccessKey ID from your AccessKey pair.

Default: None

Important

Required if the bucket ACL is public-read or private.
Required if the Signature and policy form fields are present.

Signature

String

The HMAC-SHA1 signature calculated from the AccessKey secret and the policy. OSS validates the POST request by verifying this signature. For more information, see PostObject.

Default: None

Important

Required if the bucket ACL is public-read or private.
Required if the OSSAccessKeyId and policy form fields are present.
The field name is case-insensitive; the field value is case-sensitive.

Policy

The policy form field contains a JSON document that defines permissions and constraints for uploading an object to OSS using an HTML form.

Important

A policy must contain the expiration and conditions fields.

{
  "expiration": "2023-12-03T13:00:00.000Z",
  "conditions": [
    {"bucket": "examplebucket"},
    ["content-length-range", 1, 10],
    ["eq", "$success_action_status", "201"],
    ["starts-with", "$key", "user/eric/"],
    ["in", "$content-type", ["image/jpeg", "image/png"]],
    ["not-in", "$cache-control", ["no-cache"]]
  ]
}

The following section describes the policy fields:

expiration
Specifies the expiration time of the policy in the ISO 8601 GMT format. For example, if you set this parameter to 2023-12-03T13:00:00.000Z, the POST request must be initiated before 13:00 UTC on December 3, 2023.

conditions

Specifies the valid values for form fields in the POST request.

Field	Type	Required	Description	Condition matching modes
bucket	String	No	The `bucket` name.	bucket
content-length-range	String	No	The minimum and maximum size, in bytes, of the `object` to upload.	content-length-range
success_action_status	String	No	The HTTP status code to return after a successful upload.	eq, eq-ci, starts-with, starts-with-ci, in, in-ci, not-in, not-in-ci
key	String	No	The name of the `object` to upload.	eq, eq-ci, starts-with, starts-with-ci, in, in-ci, not-in, not-in-ci
content-type	String	No	The MIME type of the uploaded `object`.	eq, eq-ci, starts-with, starts-with-ci, in, in-ci, not-in, not-in-ci
cache-control	String	No	Specifies the caching behavior of the `object`.	eq, eq-ci, starts-with, starts-with-ci, in, in-ci, not-in, not-in-ci

Condition matching modes

Condition matching mode	Description
content-length-range	Restricts the `object` size to a specific range. For example, to allow uploads between 1 and 10 bytes, specify `["content-length-range", 1, 10]`.
eq	Exact match (case-sensitive). For example, to require the `key` field to be `"a"`, specify `["eq", "$key", "a"]`.
starts-with	Prefix match (case-sensitive). For example, to require the `key` to start with `user/user1`, specify `["starts-with", "$key", "user/user1"]`.
in	Value must be in a list (case-sensitive). For example, to allow multiple image formats for `PostObject` uploads, specify `["in", "$content-type", ["image/jpeg", "image/png"]]`.
not-in	Value must not be in a list (case-sensitive). For example, to disallow the `no-cache` value for the `cache-control` header during an upload, specify `["not-in", "$cache-control", ["no-cache"]]`.
eq-ci	Exact match (case-insensitive). The content is converted to lowercase for comparison. For example, if you specify `["eq-ci", "$key", "AbC"]`, the `object` names `"abc"`, `"ABC"`, and `"aBc"` are all matched.
starts-with-ci	Prefix match (case-insensitive). The content is converted to lowercase for comparison. For example, if you specify `["starts-with-ci", "$key", "User/"]`, values that start with `"user/"`, `"USER/"`, or `"User/"` are all matched.
in-ci	Value must be in a list (case-insensitive). The content is converted to lowercase for comparison. For example, if you specify `["in-ci", "$content-type", ["IMAGE/JPEG", "image/PNG"]]`, values such as `"image/jpeg"` and `"IMAGE/PNG"` are all matched.
not-in-ci	Value must not be in a list (case-insensitive). The content is converted to lowercase for comparison. For example, if you specify `["not-in-ci", "$cache-control", ["No-Cache"]]`, values such as `"no-cache"`, `"NO-CACHE"`, and `"No-Cache"` are all excluded.

Policy escape characters

In a POST policy, $ denotes a variable. To include a literal $, you must escape it as \$. The following table describes characters that require escaping in the policy JSON.

Escape sequence	Description
\/	Forward slash
\\	Backslash
\	Double quotation mark
\$	Dollar sign
\b	Backspace
\f	Form feed
\n	Line break
\r	Carriage return
\t	Horizontal tab
\uxxxx	Unicode character

Signature calculation process

Create a UTF-8 encoded policy.
Construct the StringToSign.
Base64-encode the policy to create a transport-safe string. This string serves as the StringToSign.
Calculate the signature.
Sign the string with your AccessKey secret using the following formula: Signature = base64(hmac-sha1(AccessKeySecret,base64(policy))).

Java example: POST signature calculation

The following Java example demonstrates how to calculate a POST signature based on the policy provided above.

import org.apache.commons.codec.binary.Base64;

public class Demo {
    public static void main(String[] args) {
        // Before you run this code example, make sure that the OSS_ACCESS_KEY_SECRET environment variable is set.
        String accessKeySecret =  System.getenv().get("OSS_ACCESS_KEY_SECRET");

        // Step 1: Create the policy.
        String policy = "{\n" +
                "  \"expiration\": \"2023-12-03T13:00:00.000Z\",\n" +
                "  \"conditions\": [\n" +
                "    {\"bucket\": \"examplebucket\"},\n" +
                "    [\"content-length-range\", 1, 10],\n" +
                "    [\"eq\", \"$success_action_status\", \"201\"],\n" +
                "    [\"starts-with\", \"$key\", \"user/eric/\"],\n" +
                "    [\"in\", \"$content-type\", [\"image/jpeg\", \"image/png\"]],\n" +
                "    [\"not-in\", \"$cache-control\", [\"no-cache\"]]\n" +
                "  ]\n" +
                "}";

        // Step 2: Construct the StringToSign.
        String stringToSign = new String(Base64.encodeBase64(policy.getBytes()));

        // Step 3: Calculate the signature.
        String signature = com.aliyun.oss.common.auth.ServiceSignature.create().computeSignature(accessKeySecret, stringToSign);
        System.out.println("signature:" + signature);
    }
}

Sample result:

signature:hR2cJnoG9uzrZLDAmrfOtUjtkSM=