A V1 signature in a PostObject request - Object Storage Service

To ensure the security of a PostObject request, you must include a signature in the PostObject request. A V1 signature in a PostObject request is calculated by encrypting a series of request parameters, including policy and expiration, based on an AccessKey secret. After the application server generates a signature, the application server returns information including the signature and upload policy to the client. The client uses the information to create an upload request. After Object Storage Service (OSS) receives the upload request, OSS verifies the validity of the signature. Only requests that include a valid signature are allowed. Requests that fail the signature verification are denied.

Important

We recommend that you use the V4 signature algorithm, which provides better security. For more information, see (Recommended) Include a V4 signature in a PostObject request.

Signature in a PostObject request

PostObject requests support the V1 signature algorithm. The form elements and policy form field play a key role in ensuring the legitimacy and security of PostObject requests.

Form elements

A form is a collection of fields that are actually carried in a PostObject request to pass information about the object that you want to upload and its metadata. The following table describes the unique form elements of a V1 signature in a PostObject request. For more information about the common form elements, see Form elements.

Element

Type

Description

OSSAccessKeyId

String

The AccessKey ID of the AccessKey pair.

By default, this element is left empty.

Important

If the bucket access control list (ACL) is public-read or private, you must provide the OSSAccessKeyId element.
If the Signature element and policy form field exist, you must provide the OSSAccessKeyId element.

Signature

String

The signature calculated based on the AccessKey secret and policy. OSS uses the signature to verify the validity of the PostObject request. For more information, see PostObject.

By default, this element is left empty.

Important

If the bucket ACL is public-read or private, you must provide the Signature element.
If the OSSAccessKeyId element and policy form field exist, you must provide the Signature element.
The key of the element is case-insensitive, but the value of the form field is case-sensitive.

policy

The policy form field in a PostObject request is used to specify the expiration time and conditions of the PostObject request that you initiate to upload an object by using an HTML form. The value of the policy form field is a JSON string that restricts a PostObject request by specifying multiple parameters, such as the bucket name to which you want to upload the object, the prefix in the object name, the validity period of the request, the allowed HTTP methods, and the object size and content.

Important

The policy form field must contain the expiration and conditions parameters.

{
  "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/jpg", "image/png"]],
    ["not-in", "$cache-control", ["no-cache"]]
  ]
}

Required parameters in the policy form field

expiration
The expiration parameter specifies the expiration time of the request. The time must follow the ISO 8601 standard and must be in GMT. For example, 2023-12-03T13:00:00.000Z specifies that the PostObject request must be sent before 13:00 on December 3, 2013.

conditions

The conditions parameter is a list that specifies the valid values of the form fields in the PostObject request.

Parameter	Type	Required	Description	Matching mode
bucket	String	No	The name of the bucket.	bucket
content-length-range	String	No	The allowed minimum and maximum sizes of the object that you want to upload. Unit: bytes.	content-length-range
success_action_status	String	No	The HTTP status code that is returned after the object is uploaded.	eq, starts-with, in, and not-in
key	String	No	The name of the object that you want to upload.	eq, starts-with, in, and not-in
content-type	String	No	The type of the object that you want to upload.	eq, starts-with, in, and not-in
cache-control	String	No	The caching behavior of the object.	eq, starts-with, in, and not-in

Condition matching modes

Matching mode	Description
content-length-range	The size of the object that you want to upload must be within the range of the supported object size. For example, if the supported object size is 1 to 10 bytes, the condition must be ["content-length-range", 1, 10].
eq	The value of a form field must be exactly the same as the value that is specified in the conditions. For example, if the value of the key form field must be a, you can specify ["eq", "$key", "a"] as the condition.
starts-with	The value of a form field must start with a specific prefix. For example, if the value of the key form field starts with user/user1, you can specify ["starts-with", "$key", "user/user1"] as the condition.
in	The elements that you want to include in the verification. The elements must be specified in the condition string. For example, if you want to verify whether the type of the object that you want to upload is image and want to allow images of multiple formats to be uploaded in a PostObject request, the condition must be ["in", "$content-type", ["image/jpg", "image/png"]].
not-in	The elements that you want to exclude from the verification. The elements must be specified in the condition string. For example, if you want to specify the object caching behavior and exclude the no-cache element, the condition must be ["not-in", "$cache-control", ["no-cache"]].

Escape characters for the policy form field

In the policy form field of a PostObject request, the dollar sign ($) indicates a variable. To describe the dollar sign ($), you must use the following escape character: \$. The following table describes the escape characters used in the JSON string of the policy form field in a PostObject request.

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

Signature calculation process

Create a UTF-8 encoded policy.
Create a string to sign.
Base64-encode the policy to generate a string that can be transmitted securely as the string to sign.
Calculate the signature.
Sign the string to sign by using the AccessKey secret based on the following method: Signature = base64(hmac-sha1(AccessKeySecret,base64(policy))).

Examples

The following sample code provides an example on how to use the preceding policy to calculate a V1 signature for a PostObject request by using OSS SDK for Java:

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

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

        // Step 1: Create a 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/jpg\", \"image/png\"]],\n" +
                "    [\"not-in\", \"$cache-control\", [\"no-cache\"]]\n" +
                "  ]\n" +
                "}";

        // Step 2: Create a string to sign. 
        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 output:

signature:hR2cJnoG9uzrZLDAmrfOtUjtkSM=