Security policies
The POST security policy is part of the authentication of a POST object upload request. The policy consists of base-64 encoded JSON code which is submitted as a form field in the request.
If a form contains fields that don't meet the policy's requirements, the request is rejected with the status 403.
Example
Here's an example of a POST policy using AWS Signature Version 4 conditions:
{ "expiration": "2020-11-02T123:01:00.000Z", "conditions": [ {"bucket": "Finance"}, ["starts-with", "$key", "user/user1/"], {"acl": "public-read"}, {"success_action_redirect": "http://www.company.com/success"}, {"x-amz-meta-uuid": "14365123651274"}, {"x-amz-credential": "AKIAIOSFODNN7EXAMPLE/20151229/us-east-1/s3/aws4_request"}, {"x-amz-algorithm": "AWS4-HMAC-SHA256"}, {"x-amz-date": "20201102T000000Z" } ] }
A security policy always contains the elements expiration
and conditions
. The example policy uses two condition matching types, exact matching and starts-with matching. The following sections describe these elements.
Expiration
The element expiration
specifies the expiration date and time of the security policy in ISO8601 GMT date format. For example, 2019-08-10T12:00:00.000Z specifies that the POST policy is not valid after midnight GMT on August 10, 2019.
For AWS Signature Version 4 authentication, if the field x-amz-date
contains an expired date, the policy is considered expired.
Condition matching
The table below describes condition matching types that you can use to specify POST security policy conditions. You must specify at least one condition for each field that you specify. You can create more complex matching criteria by specifying multiple conditions for a given form field. If there are multiple conditions for a field, then all the conditions must match.
Exact Matches
The form field value must match the value specified. This example indicates that the ACL must be set to public-read:
{"acl": "public-read" }
This example is an alternate way to indicate that the ACL must be set to public-read:
[ "eq", "$acl", "public-read" ]
Starts With
The value must start with the specified value. This example indicates that the object key must start with user/user1:
["starts-with", "$key", "user/user1/"]
Matching Any Content
To configure the POST security policy to allow any content within a form field, use starts-with with an empty value (""). This example allows any value for success_action_redirect:
["starts-with", "$success_action_redirect", ""]
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 MB:
["content-length-range", 1048579, 10485760]
Conditions
The conditions in a POST policy are an array of objects, any of which you can use to validate the request. You can use these conditions to restrict what is allowed in the request. For example, the policy conditions in the preceding example require the following conditions:
- The request must specify the bucket name
Finance
. - The object key name must have the prefix
user/user1
. - The object ACL must be set to
public-read
.
Each field that you specify in a form (except x-amz-signature
, AccessKeyId
, file, policy, and field names that have the prefix x-ignore-) must appear in the list of conditions.
All variables within the form are expanded before validating the security policy. Therefore, all condition matching is executed against the expanded form fields. For example, 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}" ]
).
The list below describes supported conditions.
acl
Specifies the ACL value that must be used in the submitted form.
bucket
Specifies the acceptable bucket name.
content-length-range
Specifies the minimum and maximum allowable size for the uploaded content.
If the object is compressed and the value of content-encoding is
gzip
, the size limit is applied to the size of the uncompressed object.key
Specifies the acceptable key name or a prefix of the uploaded object.
success_action_ redirect
redirect
Specifies the URL to which the client is redirected upon successful upload.
success_action_status
If you don't specify a value for
success_action_redirect
, this element specifies the status code returned to the client when the upload succeeds.x-amz-algorithm
(AWS Signature Version 4 authentication only field)
Specifies the signing algorithm that must be used during signature calculation. The value is
AWS4-HMAC-SHA256
.x-amz-credential
(AWS Signature Version 4 authentication only field)
Specifies the credentials that you used to calculate the signature. Required if you include a POST policy document with the request. Use this format:
access_key_id/date/aws_region/aws_service/aws4_request
For Amazon S3, the value of
aws_service
iss3
.For example:
AKIAIOSFODNN7EXAMPLE/20191024/us-east-1/s3/aws4_request
x-amz-date
(AWS Signature Version 4 authentication only field)
Specifies a date value in ISO8601 format. Required if you include a POST policy document with the request.
For example:
20191024T000000Z
x-amz-meta-*
User-specified metadata.
x-amz-*
Other x-amz- headers.
x-hcp-retention
Specifies the retention value for the object being stored. This value can be a fixed date, an offset, a retention class, or a special value.
x-hcp-retentionhold
Specifies whether the object is on hold. This value can be either
true
orfalse
.x-ignore-*
Users can specify additional form fields with this header that should be ignored.
Character escaping
The table below describes characters that must be escaped within a security policy.
Escape sequence | Description |
\\ | Backslash |
\b | Backspace |
\f | Form feed |
\n | New line |
\r | Carriage return |
\t | Horizontal tab |
\v | Vertical tab |
\unnnn | All Unicode characters |