 | Feedback |  |
Topics
When communicating with Amazon S3, you normally use the REST or SOAP APIs to perform put, get, delete, and other operations. With POST, users upload data directly to Amazon S3 through their browsers, which do not understand SOAP APIs or how to make a REST PUT request.
To allow users to upload content to Amazon S3 using their browsers, you use HTML forms. HTML Forms consist of a form declaration and form fields. The form declaration contains high level information about the request. The form fields contain detailed information about the request as well as the policy that is used to authenticate it and make sure that it meets conditions that you specify.
![[Note]](images/note.png) | Note |
|---|---|
The form data and boundaries (excluding the contents of the file) cannot exceed 20K. |
This section describes how to use HTML forms.
The form and policy must be UTF-8 encoded. You can apply UTF-8 encoding to the form by specifying it in the HTML heading or as a request header.
| Note |
|---|---|
The HTML form declaration does not accept query string authentication parameters. For information about query string authentication, see Query String Authentication. |
Following is an example of UTF-8 encoding in the HTML heading.
<html>
<head>
...
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
...
</head>
<body>
Following is an example of UTF-8 encoding in a request header.
Content-Type: text/html; charset=UTF-8
The form declaration has three components: the action, the method, and the enclosure type. If any of these values is improperly set, the request fails.
The action specifies the URL that processes the request, which must be set to the URL of the bucket. For example, if the name of your bucket is "johnsmith", the URL is "http://johnsmith.s3.amazonaws.com/".
| Note |
|---|---|
The key name is specified in a form field. |
The method must be POST.
The enclosure type (enctype) must be specified and must be set to multipart/form-data (go to RFC 1867) for both file uploads and text area uploads.
Example
This is a form declaration for the bucket "johnsmith".
<form action="http://johnsmith.s3.amazonaws.com/" method="post" enctype="multipart/form-data">
Following is a table that describes a list of fields that can be used within a form.
| Note |
|---|---|
The variable |
| Element Name | Description | Required? | |||
|---|---|---|---|---|---|
| AWSAccessKeyId | The AWS Access Key ID of the owner of the bucket who grants an Anonymous user access for a request that satisfies the set of constraints in the Policy. This is required if a policy document is included with the request. | Conditional | |||
| acl | Specifies an Amazon S3 access control list. Options include private, public-read, public-read-write, authenticated-read. The default setting is private. If an invalid access control list is specified, an error is generated. For more information on ACLs, see Access Control Lists. | No | |||
| Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires | REST-specific headers. For more information, see PUT Object. | No | |||
| key | The name of the uploaded key. To use the filename provided by the user, use the ${filename} variable. For example, if the user Betty uploads the file the file lolcatz.jpg and you specify /user/betty/${filename}, the file is stored as /user/betty/lolcatz.jpg. For more information, see Keys. | Yes | |||
| policy | Security Policy describing what is permitted in the request. Requests without a security policy are considered anonymous and only work on publicly writable buckets. For more information, see Policy Construction | No | |||
| success_action_redirect, redirect | The URL to which the client is redirected upon successful upload. If success_action_redirect is not specified, Amazon S3 returns the empty document type specified in the success_action_status field. If Amazon S3 cannot interpret the URL, it acts as if the field is not present. If the upload fails, Amazon S3 displays an error and does not redirect the user to a URL. For more information, see Redirection.
| No | |||
| success_action_status | The status code returned to the client upon successful upload if success_action_redirect is not specified. Accepts the values 200, 201, or 204 (default). If the value is set to 200 or 204, Amazon S3 returns an empty document with a 200 or 204 status code. If the value is set to 201, Amazon S3 returns an XML document with a 201 status code. For information on the content of the XML document, see POST Response Body. If the value is not set or if it is set to an invalid value, Amazon S3 returns an empty document with a 204 status code.
| No | |||
| signature | The HMAC signature constructed using the secret key of the provided AWSAccessKeyID. For more information, see Policy Construction and Authentication and Access Control. | No | |||
| x-amz-security-token | Amazon DevPay security token. Each request that uses Amazon DevPay requires two For more information, see Using Amazon DevPay with Amazon S3. | No | |||
| Other field names prefixed with x-amz-meta- | User-specified metadata. Amazon S3 does not validate or use this data. For more information, see PUT Object. | No | |||
| file | File or text content. The file or text content must be the last field in the form. You cannot upload more than one file at a time. | Yes |
The policy is a UTF-8 and Base64 encoded JSON document that specifies conditions which the request must meet and is used to authenticate the content. Depending on how you design your policy documents, you can use them per-upload, per-user, for all uploads, or according to other designs that meet your needs.
| Note |
|---|---|
Although the policy document is optional, we highly recommend it over making a bucket publicly writable. |
Following is an example of a policy document.
{ "expiration": "2007-12-01T12:00:00.000Z",
"conditions": [
{"acl": "public-read" },
{"bucket": "johnsmith" },
["starts-with", "$key", "user/eric/"],
]
}
The policy document contains the expiration and conditions.
The expiration specifies the expiration date of the policy in ISO8601 GMT date format. For example, "2007-12-01T12:00:00.000Z" specifies that the policy is not valid after 12:00 GMT on 2007-12-01.
The conditions in the policy document are used to validate the contents of the uploaded object. Each form field that you specify in the form (except AWSAccessKeyId , signature, file, policy, and field names that have an x-ignore- prefix) must be included in the list of conditions.
| Note |
|---|---|
If you have multiple fields with the same name, the values must be separated by commas. For example, if you have two fields named "x-amz-meta-tag" and the first one has a value of "Ninja" and second has a value of "Stallman", you would set the policy document to
All variables within the form are expanded prior to validating the policy.
Therefore, all condition matching should be against the expanded fields.
For example, if you set the key field to |
Policy document conditions are described in the following table.
| Element Name | Description |
|---|---|
| acl | Specifies conditions the ACL must meet. Supports exact matching and |
| content-length-range | Specifies the minimum and maximum allowable size for the uploaded content. Supports range matching. |
| Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires | REST-specific headers. Supports exact matching and |
| key | The name of the uploaded key. Supports exact matching and |
| success_action_redirect, redirect | The URL to which the client is redirected upon successful upload. Supports exact matching and |
| success_action_status | The status code returned to the client upon successful upload if success_action_redirect is not specified. 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 Amazon DevPay with Amazon S3. |
| Other field names prefixed with x-amz-meta- | User-specified metadata. Supports exact matching and |
| Note |
|---|---|
If your toolkit adds additional fields (e.g., Flash adds filename), you must add them to the policy document. If you can control this functionality, prefix |
Following is a table that describes condition matching types. Although you must specify 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 | Description |
|---|---|
|
Exact Matches |
Exact matches verify that fields match specific values. 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 |
If the value must start with a certain value, use starts-with. This example indicates that the key must start with user/betty: ["starts-with", "$key", "user/betty/"] |
|
Matching Any Content |
To configure the policy to allow any content within a field, use starts-with with an empty value. This example allows any success_action_redirect: ["starts-with", "$success_action_redirect", ""] |
|
Specifying Ranges |
For fields that accept ranges, separate the upper and lower ranges with a comma. This example allows a file size from 1 to 10 megabytes: ["content-length-range", 1048579, 10485760] |
| Step | Description |
|---|---|
| 1 | Encode the policy using UTF-8. |
| 2 | Encode those UTF-8 bytes using Base64. |
| 3 | Sign the policy with your Secret Access Key using HMAC SHA-1. |
| 4 | Encode the SHA-1 signature using Base64. |
For information about constructing the policy, see Policy Construction. For general information about authentication, see Authentication and Access Control.
On completion of the POST, the user is redirected to the location that you specified in the success_action_redirect field. If Amazon S3 cannot interpret the URL, it ignores the success_action_redirect field.
If success_action_redirect is not specified, Amazon S3 returns the empty document type specified in the success_action_status field.
If the POST fails, Amazon S3 displays an error and does not provide a redirect.
