/aws4_request `For example: ` AKIAIOSFODNN7EXAMPLE/20130728/us-east-1/s3/aws4_request` ` ` For Amazon S3, the aws-service string is s3. For a list of Amazon S3 aws-region strings, see [Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) in the AWS General Reference. This is required if a policy document is included with the request. | Required for authenticated requests |
| x-amz-date | It is the date value in ISO8601 format. For example, `20130728T000000Z`. It is the same date you used in creating the signing key (for example, 20130728). This must also be the same value you provide in the policy (`x-amz-date`) that you signed. This is required if a policy document is included with the request. | Required for authenticated requests |
| x-amz-security-token | A security token used by Amazon DevPay and session credentials If the request is using Amazon DevPay, it requires two `x-amz-security-token` form fields: one for the product token and one for the user token. For more information, see [Using DevPay](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingDevPay.html) in the *Amazon Simple Storage Service User Guide*. If the request is using session credentials, it requires one `x-amz-security-token` form. For more information, see [Requesting Temporary Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html) in the *IAM User Guide*. | No |
| x-amz-signature | (AWS Signature Version 4) The HMAC-SHA256 hash of the security policy. This field is required if a policy document is included with the request. | Required for authenticated requests |
| x-amz-meta-\$1 | Field names starting with this prefix are user-defined metadata. Each one is stored and returned as a set of key-value pairs. Amazon S3 doesn't validate or interpret user-defined metadata. For more information, see [PutObject](API_PutObject.md). | No |
| x-amz-\$1 | See POST Object ([POST Object](RESTObjectPOST.md) for other `x-amz-*` headers. | No |
| file | File or text content. The file or content must be the last field in the form. You cannot upload more than one file at a time. | Yes |
Conditional items are required for authenticated requests and are optional for anonymous requests.
Now that you know how to create forms, next you can create a security policy that you can sign. For more information, see [POST Policy](sigv4-HTTPPOSTConstructPolicy.md).
# POST Policy
**Topics**
+ [
## Expiration
](#sigv4-HTTPPOSTExpiration)
+ [
## Condition Matching
](#sigv4-ConditionMatching)
+ [
## Conditions
](#sigv4-PolicyConditions)
+ [
## Character Escaping
](#sigv4-HTTPPOSTEscaping)
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 AWS Signature Version 4)](sigv4-post-example.md).
**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.
```
1. { "expiration": "2007-12-01T12:00:00.000Z",
2. "conditions": [
3. {"acl": "public-read" },
4. {"bucket": "johnsmith" },
5. ["starts-with", "$key", "user/eric/"],
6. ]
7. }
```
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: {"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 Content-Types in a Comma-Separated List | Content-Types values for a `starts-with` condition that include commas are interpreted as lists. Each value in the list must meet the condition for the whole condition to pass. For example,given the following condition: ["starts-with", "$Content-Type", "image/"]
The following value would pass the condition: "image/jpg,image/png,image/gif"
The following value would not pass the condition: ["image/jpg,text/plain"]
Data elements other than `Content-Type` are treated as strings, regardless of the presence of commas. |
| Matching Any Content | To configure the POST 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 MiB: ["content-length-range", 1048576, 10485760]
|
The specific conditions supported in a POST policy are described in [Conditions](#sigv4-PolicyConditions).
## 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](#sigv4-ConditionMatching).
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 `starts-with` condition match type discussed in the following section. |
| 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 `content-length-range` condition match type. |
| Cache-Control `Content-Type` `Content-Disposition` `Content-Encoding` `Expires` | REST-specific headers. For more information, see [POST Object](RESTObjectPOST.md). This condition supports exact matching and `starts-with` condition match type. |
| key | The acceptable key name or a prefix of the uploaded object. This condition supports exact matching and `starts-with` condition match type. |
| success\$1action\$1redirect `redirect` | The URL to which the client is redirected upon successful upload. This condition supports exact matching and `starts-with` condition match type. |
| success\$1action\$1status | The status code returned to the client upon successful upload if `success_action_redirect` is not specified. This condition supports exact matching. |
| x-amz-algorithm | The signing algorithm that must be used during signature calculation. For AWS Signature Version 4, the value is `AWS4-HMAC-SHA256`. 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: `////aws4_request` For example: ` AKIAIOSFODNN7EXAMPLE/20130728/us-east-1/s3/aws4_request` For Amazon S3, the aws-service string is `s3`. For a list of Amazon S3 `aws-region` strings, see [Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) in the *AWS General Reference*. This is required if a POST policy document is included with the request. This condition supports exact matching. |
| x-amz-date | The date value specified in the ISO8601 formatted string. For example, `20130728T000000Z`. The date must be same that you used in creating the signing key for signature calculation. 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 `x-amz-security-token` form fields: one for the product token and one for the user token. As a result, the values must be separated by commas. For example, if the user token is `eW91dHViZQ==` and the product token is `b0hnNVNKWVJIQTA=`, you set the POST policy entry to: `{ "x-amz-security-token": "eW91dHViZQ==,b0hnNVNKWVJIQTA=" }`. For more information about Amazon DevPay, see [Using DevPay](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingDevPay.html) in the *Amazon Simple Storage Service User Guide*. |
| x-amz-meta-\$1 | User-specified metadata. This condition supports exact matching and `starts-with` condition match type. |
| x-amz-\$1 | See POST Object ([POST Object](RESTObjectPOST.md) for other `x-amz-*` headers. 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 |
| --- | --- |
| \$1\$1 | Backslash |
| \$1\$1 | Dollar symbol |
| \$1b | Backspace |
| \$1f | Form feed |
| \$1n | New line |
| \$1r | Carriage return |
| \$1t | Horizontal tab |
| \$1v | Vertical tab |
| \$1u*xxxx* | 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 AWS Signature Version 4)](sigv4-post-example.md).
# Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version 4)
This section shows an example of using an HTTP POST request to upload content directly to Amazon S3.
For more information on Signature Version 4, see [Signature Version 4 Signing Process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).
## Uploading a File to Amazon S3 Using HTTP POST
This example provides a sample POST policy and a form that you can use to upload a file. The topic uses the example policy and fictitious credentials to show you the workflow and resulting signature and policy hash. You can use this data as test suite to verify your signature calculation code.
The example uses the following example credentials the signature calculations. You can use these credentials to verify your signature calculation code. However, you must then replace these with your own credentials when sending requests to AWS.
| Parameter | Value |
| --- | --- |
| AWSAccessKeyId | AKIAIOSFODNN7EXAMPLE |
| AWSSecretAccessKey | wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY |
### Sample Policy and Form
The following POST policy supports uploads to Amazon S3 with specific conditions.
```
1. { "expiration": "2015-12-30T12:00:00.000Z",
2. "conditions": [
3. {"bucket": "sigv4examplebucket"},
4. ["starts-with", "$key", "user/user1/"],
5. {"acl": "public-read"},
6. {"success_action_redirect": "http://sigv4examplebucket.s3.amazonaws.com/successful_upload.html"},
7. ["starts-with", "$Content-Type", "image/"],
8. {"x-amz-meta-uuid": "14365123651274"},
9. {"x-amz-server-side-encryption": "AES256"},
10. ["starts-with", "$x-amz-meta-tag", ""],
11.
12. {"x-amz-credential": "AKIAIOSFODNN7EXAMPLE/20151229/us-east-1/s3/aws4_request"},
13. {"x-amz-algorithm": "AWS4-HMAC-SHA256"},
14. {"x-amz-date": "20151229T000000Z" }
15. ]
16. }
```
This POST policy sets the following conditions on the request:
+ The upload must occur before noon UTC on December 30, 2015.
+ The content can be uploaded only to the `sigv4examplebucket`. The bucket must be in the region that you specified in the credential scope (`x-amz-credential` form parameter), because the signature you provided is valid only within this scope.
+ You can provide any key name that starts with `user/user1`. For example, `user/user1/MyPhoto.jpg`.
+ The ACL must be set to `public-read`.
+ If the upload succeeds, the user's browser is redirected to `http://sigv4examplebucket.s3.amazonaws.com/successful_upload.html`.
+ The object must be an image file.
+ The `x-amz-meta-uuid` tag must be set to `14365123651274`.
+ The `x-amz-meta-tag` can contain any value.
The following is a Base64-encoded version of this POST policy. You use this value as your StringToSign in signature calculation.
```
1. eyAiZXhwaXJhdGlvbiI6ICIyMDE1LTEyLTMwVDEyOjAwOjAwLjAwMFoiLA0KICAiY29uZGl0aW9ucyI6IFsNCiAgICB7ImJ1Y2tldCI6ICJzaWd2NGV4YW1wbGVidWNrZXQifSwNCiAgICBbInN0YXJ0cy13aXRoIiwgIiRrZXkiLCAidXNlci91c2VyMS8iXSwNCiAgICB7ImFjbCI6ICJwdWJsaWMtcmVhZCJ9LA0KICAgIHsic3VjY2Vzc19hY3Rpb25fcmVkaXJlY3QiOiAiaHR0cDovL3NpZ3Y0ZXhhbXBsZWJ1Y2tldC5zMy5hbWF6b25hd3MuY29tL3N1Y2Nlc3NmdWxfdXBsb2FkLmh0bWwifSwNCiAgICBbInN0YXJ0cy13aXRoIiwgIiRDb250ZW50LVR5cGUiLCAiaW1hZ2UvIl0sDQogICAgeyJ4LWFtei1tZXRhLXV1aWQiOiAiMTQzNjUxMjM2NTEyNzQifSwNCiAgICB7IngtYW16LXNlcnZlci1zaWRlLWVuY3J5cHRpb24iOiAiQUVTMjU2In0sDQogICAgWyJzdGFydHMtd2l0aCIsICIkeC1hbXotbWV0YS10YWciLCAiIl0sDQoNCiAgICB7IngtYW16LWNyZWRlbnRpYWwiOiAiQUtJQUlPU0ZPRE5ON0VYQU1QTEUvMjAxNTEyMjkvdXMtZWFzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LA0KICAgIHsieC1hbXotYWxnb3JpdGhtIjogIkFXUzQtSE1BQy1TSEEyNTYifSwNCiAgICB7IngtYW16LWRhdGUiOiAiMjAxNTEyMjlUMDAwMDAwWiIgfQ0KICBdDQp9
```
When you copy/paste the preceding policy, it should have carriage returns and new lines for your computed hash to match this value (ie. ASCII text, with CRLF line terminators).
Using example credentials to create a signature, the signature value is as follows (in signature calculation, the date is same as the `x-amz-date` in the policy (20151229):
```
8afdbf4008c03f22c2cd3cdb72e4afbb1f6a588f3255ac628749a66d7f09699e
```
The following example form specifies the preceding POST policy and supports a POST request to the `sigv4examplebucket`. Copy/paste the content in a text editor and save it as exampleform.html. You can then upload image files to the specific bucket using the exampleform.html. Your request will succeed if the signature you provide matches the signature Amazon S3 calculates.
**Note**
You must update the bucket name, dates, credential, policy, and signature with valid values for this to successfully upload to S3.
```
1.
2.
3.
4.
5.
6.
7.
8.
9.
31.
32.
```
The post parameters are case insensitive. For example, you can specify `x-amz-signature` or `X-Amz-Signature`.
# Browser-based uploads to Amazon S3 using the AWS Amplify library
This section describes how to upload files to Amazon S3 using the AWS Amplify JavaScript library.
For information about setting up the AWS Amplify library, see [AWS Amplify Installation and Configuration](https://aws.github.io/aws-amplify/).
## Using the AWS Amplify JavaScript library to Upload Files to Amazon S3
The AWS Amplify library `Storage` module gives a simple browser-based upload mechanism for managing user content in public or private Amazon S3 storage.
**Example : AWS Amplify Manual Setup**
The following example shows the manual setup for using the AWS Amplify Storage module. The default implementation of the Storage module uses Amazon S3.
```
import Amplify from 'aws-amplify';
Amplify.configure(
Auth: {
identityPoolId: 'XX-XXXX-X:XXXXXXXX-XXXX-1234-abcd-1234567890ab', //REQUIRED - Amazon Cognito Identity Pool ID
region: 'XX-XXXX-X', // REQUIRED - Amazon Cognito Region
userPoolId: 'XX-XXXX-X_abcd1234', //OPTIONAL - Amazon Cognito User Pool ID
userPoolWebClientId: 'XX-XXXX-X_abcd1234', //OPTIONAL - Amazon Cognito Web Client ID
},
Storage: {
bucket: '', //REQUIRED - Amazon S3 bucket
region: 'XX-XXXX-X', //OPTIONAL - Amazon service region
}
);
```
**Example : Put data into Amazon S3**
The following example shows how to `put` public data into Amazon S3.
```
Storage.put('test.txt', 'Hello')
.then (result => console.log(result))
.catch(err => console.log(err));
```
The following example shows how to `put` private data into Amazon S3.
```
Storage.put('test.txt', 'Private Content', {
level: 'private',
contentType: 'text/plain'
})
.then (result => console.log(result))
.catch(err => console.log(err));
```
For more information about using the AWS Amplify Storage module, see [AWS Amplify Storage](https://aws.github.io/aws-amplify/media/storage_guide.html).
## More Info
[AWS Amplify Quick Start](https://aws.github.io/aws-amplify/)