Creating an HTML Form (Using Amazon Signature Version 4)
To allow users to upload content to Amazon S3 by using their browsers (HTTP POST requests), 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 request information.
This section describes how to create HTML forms. For a working example of browser-based upload using HTTP POST and related signature calculations for request authentication, see Example: Browser-Based Upload using HTTP POST (Using Amazon Signature Version 4).
The form and policy must be UTF-8 encoded. You can apply UTF-8 encoding to the form by
specifying charset=UTF-8
in the content
attribute. The
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
Note
The form data and boundaries (excluding the contents of the file) cannot exceed 20KB.
HTML Form Declaration
The HTML form declaration has the following three attributes:
-
action
– The URL that processes the request, which must be set to the URL of the bucket. For example, if the name of your bucket isexamplebucket
, the URL ishttp://examplebucket.s3.amazonaws.com/
.Note
The key name is specified in a form field.
-
method
– The method must be POST. -
enctype
– The enclosure type (enctype
) must be set to multipart/form-data for both file uploads and text area uploads. For more information aboutenctype
, see RFC 1867.
This is a form declaration for the bucket examplebucket
.
<form action="http://examplebucket.s3.amazonaws.com/" method="post" enctype="multipart/form-data">
HTML Form Fields
The following table describes a list of fields that you can use within a form. Among other
fields, there is a signature field that you can use to authenticate requests. There
are fields for you to specify the signature calculation algorithm
(x-amz-algorithm
), the credential scope
(x-amz-credential
) that you used to generate the signing key, and
the date (x-amz-date
) used to calculate the signature. Amazon S3 uses this
information to re-create the signature. If the signatures match, Amazon S3 processes the
request.
Note
The variable ${filename}
is automatically replaced with the name of the file
provided by the user and is recognized by all form fields. If the browser or
client provides a full or partial path to the file, only the text following the
last slash (/) or backslash (\) is used (for example, C:\Program
Files\directory1\file.txt
is interpreted as file.txt
).
If no file or file name is provided, the variable is replaced with an empty
string.
If you don't provide elements required for authenticated requests, such as the
policy
element, the request is assumed to be anonymous and will
succeed only if you have configured the bucket for public read and write.
Element Name | Description | Required |
---|---|---|
acl |
An Amazon S3 access control list (ACL). If an invalid ACL is specified, Amazon S3 denies the request. For more information about ACLs, see Using Amazon S3 ACLs. Type: String Default: private
Valid Values: |
No |
Cache-Control
|
REST-specific headers. For more information, see PutObject. |
No |
key |
The key name of the uploaded object. To use the file name provided by the user, use the ${filename}
variable. For example, if you upload a file
For more information, see Object Key and Metadata in the Amazon Simple Storage Service User Guide. |
Yes |
policy |
The base64-encoded security policy that describes what is permitted in the request. For authenticated requests, a policy is required. Requests without a security policy are considered anonymous and will succeed only on a publicly writable bucket. |
Required for authenticated requests |
success_action_redirect |
The URL to which the client is redirected upon successful upload. If If the upload fails, Amazon S3 returns an error and does not redirect the user to another URL. |
No |
success_action_status |
The status code returned to the client upon successful upload
if Valid values are If the value is set to 200 or 204, Amazon S3 returns an empty document with the specified status code. If the value is set to 201, Amazon S3 returns an XML document with a 201 status code. For information about the content of the XML document, see POST Object. If the value is not set or is invalid, Amazon S3 returns an empty document with a 204 status code. NoteSome versions of the Adobe Flash player do not properly
handle HTTP responses with an empty body. To support uploads
through Adobe Flash, we recommend setting
|
No |
x-amz-algorithm |
The signing algorithm used to authenticate the request. For
Amazon Signature Version 4, the value is
This field is required if a policy document is included with the request. |
Required for authenticated requests |
x-amz-credential |
In addition to your access key ID, this field also provides 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 s3 . For a list of Amazon S3 aws-region
strings, see Regions and
Endpoints in the Amazon Web Services 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,
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 ( 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
If the request is using session credentials, it requires one
|
No |
x-amz-signature |
(Amazon 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-* |
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. |
No |
x-amz-* |
See POST Object (POST Object for other
|
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.