POST Policy
The policy required for making authenticated requests using HTTP POST is a UTF-8 and base64-encoded document written in JavaScript Object Notation (JSON) that specifies conditions that the request must meet. Depending on how you design your policy document, you can control the access granularity per-upload, per-user, for all uploads, or according to other designs that meet your needs.
This section describes the POST policy. For example signature calculations using POST policy, see Example: Browser-Based Upload using HTTP POST (Using Amazon Signature Version 4).
Note
Although the policy document is optional, we highly recommend that you use one in order to control what is allowed in the request. If you make the bucket publicly writable, you have no control at all over which users can write to your bucket.
The following is an example of a POST policy document.
{ "expiration": "2007-12-01T12:00:00.000Z", "conditions": [ {"acl": "public-read" }, {"bucket": "johnsmith" }, ["starts-with", "$key", "user/eric/"], ] }
The POST policy always contains the expiration
and
conditions
elements. The example policy uses two condition matching
types (exact matching and starts-with matching). The following sections describe these
elements.
Expiration
The expiration
element specifies the expiration date and time of the
POST policy in ISO8601 GMT date format. For example,
2013-08-01T12:00:00.000Z
specifies that the POST policy is not
valid after midnight GMT on August 1, 2013.
Condition Matching
Following is a table that describes condition matching types that you can use to specify POST policy conditions (described in the next section). Although you must specify at least one condition for each form field that you specify in the form, you can create more complex matching criteria by specifying multiple conditions for a form field.
Condition Match Type | Description |
---|---|
Exact Matches |
The form field value must match the value specified. This example indicates that the ACL must be set to public-read:
This example is an alternate way to indicate that the ACL must be set to public-read:
|
Starts With |
The value must start with the specified value. This example indicates that the object key must start with user/user1:
|
Matching Content-Types in a Comma-Separated List |
Content-Types values for a
The following value would pass the condition:
The following value would not pass the condition:
NoteData elements other than |
Matching Any Content |
To configure the POST policy to allow any content within a
form field, use
|
Specifying Ranges |
For form fields that accept a range, separate the upper and lower limit with a comma. This example allows a file size from 1 to 10 MiB:
|
The specific conditions supported in a POST policy are described in Conditions.
Conditions
The conditions
in a POST policy is an array of objects, each of which is used
to validate the request. You can use these conditions to restrict what is allowed in
the request. For example, the preceding policy conditions require the
following:
-
Request must specify the
johnsmith
bucket name. -
Object key name must have the
user/eric
prefix. -
Object ACL must be set to
public-read
.
Each form field that you specify in a form (except x-amz-signature
,
file
, policy
, and field names that have an
x-ignore-
prefix) must appear in the list of conditions.
Note
All variables within the form are expanded prior to validating the POST policy.
Therefore, all condition matching should be against the expanded form fields.
Suppose that you want to restrict your object key name to a specific prefix
(user/user1
). In this case, you set the key form field to
user/user1/${filename}
. Your POST policy should be [
"starts-with", "$key", "user/user1/" ]
(do not enter [
"starts-with", "$key", "user/user1/${filename}" ]
). For more
information, see Condition Matching.
Policy document conditions are described in the following table.
Element Name | Description |
---|---|
acl |
Specifies the ACL value that must be used in the form submission. This condition supports exact matching and
|
bucket |
Specifies the acceptable bucket name. This condition supports exact matching condition match type. |
content-length-range |
The minimum and maximum allowable size for the uploaded content. This condition supports |
Cache-Control
|
REST-specific headers. For more information, see POST Object. This condition supports exact matching and
|
key |
The acceptable key name or a prefix of the uploaded object. This condition supports exact matching and
|
success_action_redirect
|
The URL to which the client is redirected upon successful upload. This condition supports exact matching and
|
success_action_status |
The status code returned to the client upon successful upload
if This condition supports exact matching. |
x-amz-algorithm |
The signing algorithm that must be used during signature
calculation. For Amazon Signature Version 4, the value is
This condition supports exact matching. |
x-amz-credential |
The credentials that you used to calculate the signature. It provides access key ID and scope information identifying region and service for which the signature is valid. This should be the same scope you used in calculating the signing key for signature calculation. It is a string of the following form:
For example:
For Amazon S3, the aws-service string is This condition supports exact matching. |
x-amz-date |
The date value specified in the ISO8601 formatted string. For
example, This is required if a POST policy document is included with the request. This condition supports exact matching. |
x-amz-security-token |
Amazon DevPay security token. Each request that uses Amazon DevPay requires two
For more information about Amazon DevPay, see Using DevPay in the Amazon Simple Storage Service User Guide. |
x-amz-meta-* |
User-specified metadata. This condition supports exact matching and
|
x-amz-* |
See POST Object (POST Object for other
This condition supports exact matching. |
Note
If your toolkit adds more form fields (for example, Flash adds filename
),
you must add them to the POST policy document. If you can control this
functionality, prefix x-ignore-
to the field so Amazon S3 ignores the
feature and it won't affect future versions of this feature.
Character Escaping
Characters that must be escaped within a POST policy document are described in the following table.
Escape Sequence | Description |
---|---|
\\ |
Backslash |
\$ |
Dollar symbol |
\b |
Backspace |
\f |
Form feed |
\n |
New line |
\r |
Carriage return |
\t |
Horizontal tab |
\v |
Vertical tab |
\u |
All Unicode characters |
Now that you are acquainted with forms and policies, and understand how signing works, you can try a POST upload example. You need to write the code to calculate the signature. The example provides a sample form, and a POST policy that you can use to test your signature calculations. For more information, see Example: Browser-Based Upload using HTTP POST (Using Amazon Signature Version 4).