API Reference
API Version 20060301Amazon Simple Storage Service API ReferenceAmazon Simple Storage Service API Reference
Amazon Simple Storage Service API Reference
Copyright © 2016 Amazon Web Services Inc andor its affiliates All rights reserved
Amazon＇s trademarks and trade dress may not be used in connection with any product or service that is not Amazon＇s in any
manner that is likely to cause confusion among customers or in any manner that disparages or discredits Amazon All other
trademarks not owned by Amazon are the property of their respective owners who may or may not be affiliated with connected to
or sponsored by AmazonAmazon Simple Storage Service API Reference
Table of Contents
Amazon S3 REST API Introduction 1
Common Request Headers 3
Common Response Headers 5
Error Responses 7
REST Error Responses 7
List of Error Codes 8
Authenticating Requests (AWS Signature Version 4) 15
Authentication Methods 16
Introduction to Signing Requests 16
Using an Authorization Header 17
Overview 17
Signature Calculation Transfer Payload in a Single Chunk 20
Signature Calculation Transfer Payload in Multiple Chunks 31
Using Query Parameters 38
Calculating a Signature 40
An Example 42
Examples Signature Calculations 43
Signature Calculation Examples Using Java 44
Signature Calculation Examples Using C# 45
Authenticating HTTP POST Requests 45
Calculating a Signature 47
Amazon S3 Signature Version 4 Authentication Specific Policy Keys 47
Bucket Policy Examples Using Signature Version 4 Related Condition Keys 49
BrowserBased Uploads Using POST 52
Calculating a Signature 53
Creating HTML Forms 54
HTML Form Declaration 55
HTML Form Fields 55
Creating a POST Policy 58
Expiration 59
Condition Matching 59
Conditions 60
Character Escaping 62
Upload Examples 64
File Upload 64
Additional Considerations 66
POST with Adobe Flash 66
Operations on the Service 67
GET Service 67
Description 67
Requests 67
Responses 68
Examples 69
Related Resources 69
Operations on Buckets 70
DELETE Bucket 72
Description 72
Requests 72
Responses 72
Examples 72
Related Resources 73
DELETE Bucket cors 74
Description 74
Requests 74
Responses 74
API Version 20060301
ivAmazon Simple Storage Service API Reference
Examples 74
Related Resources 75
DELETE Bucket lifecycle 76
Description 76
Requests 76
Responses 76
Examples 77
Related Resources 77
DELETE Bucket policy 78
Description 78
Requests 78
Responses 78
Examples 79
Related Resources 79
DELETE Bucket replication 80
Description 80
Requests 80
Responses 80
Examples 80
Related Resources 81
DELETE Bucket tagging 82
Description 82
Requests 82
Responses 82
Examples 82
Related Resources 83
DELETE Bucket website 84
Description 84
Requests 84
Responses 84
Examples 85
Related Resources 85
GET Bucket (List Objects) Version 2 86
Description 86
Requests 86
Responses 88
Examples 91
Related Resources 95
GET Bucket (List Objects) Version 1 96
GET Bucket accelerate 104
Description 104
Requests 104
Responses 105
Examples 105
Related Resources 106
GET Bucket acl 107
Description 107
Requests 107
Responses 107
Examples 108
Related Resources 109
GET Bucket cors 110
Description 110
Requests 110
Responses 110
Special Errors 112
Examples 112
Related Resources 112
API Version 20060301
vAmazon Simple Storage Service API Reference
GET Bucket lifecycle 113
Description 113
Requests 113
Responses 113
Special Errors 118
Examples 118
Related Resources 119
GET Bucket policy 120
Description 120
Requests 120
Responses 120
Examples 121
Related Resources 121
GET Bucket location 122
Description 122
Requests 122
GET Bucket logging 124
Description 124
Requests 124
Responses 124
Examples 125
Related Resources 126
GET Bucket notification 127
Description 127
Requests 127
Responses 127
Examples 130
Related Resources 131
GET Bucket replication 132
Description 132
Requests 132
Responses 132
Special Errors 134
Examples 134
Related Resources 134
GET Bucket tagging 136
Description 136
Requests 136
Responses 136
Examples 137
Related Resources 137
GET Bucket Object versions 139
Description 139
Requests 139
Responses 140
Examples 143
Related Resources 150
GET Bucket requestPayment 151
Description 151
Requests 151
Responses 151
Examples 152
Related Resources 152
GET Bucket versioning 153
Description 153
Requests 153
Responses 154
Examples 154
API Version 20060301
viAmazon Simple Storage Service API Reference
Related Resources 155
GET Bucket website 156
Description 156
Requests 156
Responses 156
Examples 157
Related Resources 157
HEAD Bucket 158
Description 158
Requests 158
Responses 158
Examples 159
List Multipart Uploads 160
Description 160
Requests 160
Responses 162
Examples 164
Related Actions 168
PUT Bucket 169
Description 169
Requests 169
Examples 172
Related Resources 173
PUT Bucket accelerate 174
Description 174
Requests 174
Responses 175
Examples 175
Related Resources 176
PUT Bucket acl 177
Description 177
Requests 177
Responses 181
Examples 181
Related Resources 183
PUT Bucket cors 184
Description 184
Requests 185
Responses 187
Examples 188
Related Resources 188
PUT Bucket lifecycle 190
Description 190
Requests 190
Responses 196
Examples 196
Related Resources 199
PUT Bucket policy 200
Description 200
Requests 200
Responses 200
Examples 201
Related Resources 201
PUT Bucket logging 202
Description 202
Requests 202
Responses 204
Examples 205
API Version 20060301
viiAmazon Simple Storage Service API Reference
Related Resources 206
PUT Bucket notification 207
Description 207
Requests 207
Responses 211
Examples 212
Related Resources 214
PUT Bucket replication 215
Description 215
Requests 215
Responses 218
Examples 218
Related Resources 219
PUT Bucket tagging 221
Description 221
Requests 221
Responses 222
Examples 181
Related Resources 183
PUT Bucket requestPayment 224
Description 224
Requests 224
Responses 224
Examples 225
Related Resources 225
PUT Bucket versioning 226
Description 226
Requests 226
Responses 227
Examples 228
Related Resources 229
PUT Bucket website 230
Description 230
Requests 230
Responses 234
Examples 234
Operations on Objects 238
DELETE Object 239
Description 239
Requests 239
Responses 240
Examples 240
Related Resources 242
Delete Multiple Objects 242
Description 242
Requests 242
Responses 244
Examples 246
Related Actions 250
GET Object 251
Description 251
Versioning 251
Requests 252
Responses 255
Examples 257
Related Resources 261
GET Object ACL 262
Description 262
API Version 20060301
viiiAmazon Simple Storage Service API Reference
Versioning 262
Requests 262
Responses 262
Examples 263
Related Resources 265
GET Object torrent 266
Description 266
Requests 266
Responses 266
Examples 267
Related Resources 267
HEAD Object 268
Description 268
Versioning 268
Requests 268
Responses 271
Examples 273
Sample Request for an Amazon Glacier Object 275
Sample Response Glacier Object 275
Related Resources 275
OPTIONS object 276
Description 276
Requests 276
Responses 277
Examples 278
Related Resources 278
POST Object 279
Description 279
Versioning 279
Requests 279
Examples 287
Related Resources 287
POST Object restore 288
Description 288
Requests 288
Responses 289
Examples 290
Related Resources 199
PUT Object 291
Description 291
Versioning 291
Storage Class Options 291
Access Permissions 291
Requests 292
Responses 298
Examples 299
Related Resources 302
PUT Object acl 303
Description 303
Versioning 303
Requests 303
Responses 307
Examples 307
Related Resources 309
PUT Object Copy 310
Description 310
Versioning 311
Access Permissions 291
API Version 20060301
ixAmazon Simple Storage Service API Reference
Requests 311
Responses 319
Examples 320
Related Resources 323
Initiate Multipart Upload 324
Description 324
Requests 324
Responses 329
Examples 331
Related Actions 332
Upload Part 333
Description 333
Requests 333
Responses 335
Examples 336
Related Actions 337
Upload Part Copy 338
Description 338
Requests 338
Versioning 342
Responses 342
Examples 343
Related Actions 345
Complete Multipart Upload 346
Description 346
Requests 346
Responses 347
Examples 349
Related Actions 351
Abort Multipart Upload 352
Description 352
Requests 352
Responses 352
Examples 353
Related Actions 353
List Parts 354
Description 354
Requests 354
Responses 355
Examples 357
Related Actions 359
Resources 360
Document History 362
Appendix SOAP API 372
Operations on the Service (SOAP API) 372
ListAllMyBuckets (SOAP API) 372
Operations on Buckets (SOAP API) 373
CreateBucket (SOAP API) 374
DeleteBucket (SOAP API) 375
ListBucket (SOAP API) 376
GetBucketAccessControlPolicy (SOAP API) 378
SetBucketAccessControlPolicy (SOAP API) 379
GetBucketLoggingStatus (SOAP API) 380
SetBucketLoggingStatus (SOAP API) 381
Operations on Objects (SOAP API) 382
PutObjectInline (SOAP API) 383
PutObject (SOAP API) 385
CopyObject (SOAP API) 387
API Version 20060301
xAmazon Simple Storage Service API Reference
GetObject (SOAP API) 391
GetObjectExtended (SOAP API) 396
DeleteObject (SOAP API) 396
GetObjectAccessControlPolicy (SOAP API) 397
SetObjectAccessControlPolicy (SOAP API) 398
SOAP Error Responses 399
Glossary 401
API Version 20060301
xiAmazon Simple Storage Service API Reference
Amazon S3 REST API Introduction
Welcome to the Amazon Simple Storage Service API Reference This guide explains the Amazon
Simple Storage Service (Amazon S3) application programming interface (API) It describes various
API operations related request and response structures and error codes The current version of the
Amazon S3 API is 20060301
Amazon S3 supports the REST API
Note
Support for SOAP over HTTP is deprecated but it is still available over HTTPS However new
Amazon S3 features will not be supported for SOAP We recommend that you use either the
REST API or the AWS SDKs
Read the following about authentication and access control before going to specific API topics
Requests to Amazon S3 can be authenticated or anonymous Authenticated access requires
credentials that AWS can use to authenticate your requests When making REST API calls directly
from your code you create a signature using valid credentials and include the signature in your
request For information about various authentication methods and signature calculations see
Authenticating Requests (AWS Signature Version 4) (p 15)
Making REST API calls directly from your code can be cumbersome It requires you to write the
necessary code to calculate a valid signature to authenticate your requests We recommend the
following alternatives instead
• Use the AWS SDKs to send your requests (see Sample Code and Libraries) With this option you
don＇t need to write code to calculate a signature for request authentication because the SDK clients
authenticate your requests by using access keys that you provide Unless you have a good reason
not to you should always use the AWS SDKs
• Use the AWS CLI to make Amazon S3 API calls For information about setting up the AWS CLI and
example Amazon S3 commands see the following topics
Set Up the AWS CLI in the Amazon Simple Storage Service Developer Guide
Using Amazon S3 with the AWS Command Line Interface in the AWS Command Line Interface User
Guide
You can have valid credentials to authenticate your requests but unless you have permissions you
cannot create or access Amazon S3 resources For example you must have permissions to create an
API Version 20060301
1Amazon Simple Storage Service API Reference
S3 bucket or get an object from your bucket If you use root credentials of your AWS account you have
all the permissions However using root credentials is not recommended Instead we recommend
that you create IAM users in your account and manage user permissions For more information see
Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple Storage Service
Developer Guide
API Version 20060301
2Amazon Simple Storage Service API Reference
Common Request Headers
The following table describes headers that can be used by various types of Amazon S3 REST
requests
Header Name Description
Authorization The information required for request authentication For more
information go to The Authentication Header in the Amazon
Simple Storage Service Developer Guide For anonymous
requests this header is not required
ContentLength Length of the message (without the headers) according to RFC
2616 This header is required for PUTs and operations that load
XML such as logging and ACLs
ContentType The content type of the resource in case the request content in
the body Example textplain
ContentMD5 The base64 encoded 128bit MD5 digest of the message (without
the headers) according to RFC 1864 This header can be used as
a message integrity check to verify that the data is the same data
that was originally sent Although it is optional we recommend
using the ContentMD5 mechanism as an endtoend integrity
check For more information about REST request authentication
go to REST Authentication in the Amazon Simple Storage Service
Developer Guide
Date The current date and time according to the requester Example
Wed 01 Mar 2006 120000 GMT When you specify the
Authorization header you must specify either the xamz
date or the Date header
Expect When your application uses 100continue it does not send the
request body until it receives an acknowledgment If the message
is rejected based on the headers the body of the message is not
sent This header can be used only if you are sending a body
Valid Values 100continue
API Version 20060301
3Amazon Simple Storage Service API Reference
Header Name Description
Host For pathstyle requests the value is s3amazonawscom
For virtualstyle requests the value is
BucketNames3amazonawscom For more information go to
Virtual Hosting in the Amazon Simple Storage Service Developer
Guide
This header is required for HTTP 11 (most toolkits add this
header automatically) optional for HTTP10 requests
xamzcontentsha256 When using signature version 4 to authenticate request this
header provides a hash of the request payload For more
information see Signature Calculations for the Authorization
Header Transferring Payload in a Single Chunk (AWS Signature
Version 4) (p 20) When uploading object in chunks you set
the value to STREAMINGAWS4HMACSHA256PAYLOAD to
indicate that the signature covers only headers and that there is
no payload For more information see Signature Calculations
for the Authorization Header Transferring Payload in Multiple
Chunks (Chunked Upload) (AWS Signature Version 4) (p 31)
xamzdate The current date and time according to the requester Example
Wed 01 Mar 2006 120000 GMT When you specify the
Authorization header you must specify either the xamz
date or the Date header If you specify both the value specified
for the xamzdate header takes precedence
xamzsecuritytoken This header can be used in the following scenarios
• Provide security tokens for Amazon DevPay operations—Each
request that uses Amazon DevPay requires two xamz
securitytoken headers one for the product token and one
for the user token When Amazon S3 receives an authenticated
request it compares the computed signature with the provided
signature Improperly formatted multivalue headers used to
calculate a signature can cause authentication issues
• Provide security token when using temporary security
credentials—When making requests using temporary security
credentials you obtained from IAM you must provide a security
token using this header To learn more about temporary
security credentials go to Making Requests
This header is required for requests that use Amazon DevPay
and requests that are signed using temporary security
credentials
API Version 20060301
4Amazon Simple Storage Service API Reference
Common Response Headers
The following table describes response headers that are common to most AWS S3 responses
Name Description
ContentLength The length in bytes of the body in the response
Type String
Default None
ContentType The MIME type of the content For example ContentType texthtml
charsetutf8
Type String
Default None
Connection specifies whether the connection to the server is open or closed
Type Enum
Valid Values open | close
Default None
Date The date and time Amazon S3 responded for example Wed 01 Mar 2006
120000 GMT
Type String
Default None
ETag The entity tag is a hash of the object The ETag reflects changes only to the
contents of an object not its metadata The ETag may or may not be an MD5
digest of the object data Whether or not it is depends on how the object was
created and how it is encrypted as described below
• Objects created by the PUT Object POST Object or Copy operation or
through the AWS Management Console and are encrypted by SSES3 or
plaintext have ETags that are an MD5 digest of their object data
API Version 20060301
5Amazon Simple Storage Service API Reference
Name Description
• Objects created by the PUT Object POST Object or Copy operation or
through the AWS Management Console and are encrypted by SSEC or
SSEKMS have ETags that are not an MD5 digest of their object data
• If an object is created by either the Multipart Upload or Part Copy operation
the ETag is not an MD5 digest regardless of the method of encryption
Type String
Server The name of the server that created the response
Type String
Default AmazonS3
xamzdelete
marker
Specifies whether the object returned was (true) or was not (false) a delete
marker
Type Boolean
Valid Values true | false
Default false
xamzid2 A special token that helps AWS troubleshoot problems
Type String
Default None
xamzrequest
id
A value created by Amazon S3 that uniquely identifies the request In the
unlikely event that you have problems with Amazon S3 AWS can use this
value to troubleshoot the problem
Type String
Default None
xamzversion
id
The version of the object When you enable versioning Amazon S3 generates
a random number for objects added to a bucket The value is UTF8 encoded
and URL ready When you PUT an object in a bucket where versioning has
been suspended the version ID is always null
Type String
Valid Values null | any URLready UTF8 encoded string
Default null
API Version 20060301
6Amazon Simple Storage Service API Reference
REST Error Responses
Error Responses
This section provides reference information about Amazon S3 errors
Note
SOAP support over HTTP is deprecated but it is still available over HTTPS New Amazon S3
features will not be supported for SOAP We recommend that you use either the REST API or
the AWS SDKs
Topics
• REST Error Responses (p 7)
• List of Error Codes (p 8)
REST Error Responses
When there is an error the header information contains
• ContentType applicationxml
• An appropriate 3xx 4xx or 5xx HTTP status code
The body or the response also contains information about the error The following sample error
response shows the structure of response elements common to all REST error responses
NoSuchKey
The resource you requested does not exist
mybucketmyfotojpg
4442587FB7D0A2F9
The following table explains the REST error response elements
Name Description
Code The error code is a string that uniquely identifies an error condition It is meant to
be read and understood by programs that detect and handle errors by type For
more information see List of Error Codes (p 8)
Type String
Ancestor Error
API Version 20060301
7Amazon Simple Storage Service API Reference
List of Error Codes
Name Description
Error Container for all error elements
Type Container
Ancestor None
Message The error message contains a generic description of the error condition in English
It is intended for a human audience Simple programs display the message directly
to the end user if they encounter an error condition they don＇t know how or don＇t
care to handle Sophisticated programs with more exhaustive error handling and
proper internationalization are more likely to ignore the error message
Type String
Ancestor Error
RequestId ID of the request associated with the error
Type String
Ancestor Error
Resource The bucket or object that is involved in the error
Type String
Ancestor Error
Many error responses contain additional structured data meant to be read and understood by a
developer diagnosing programming errors For example if you send a ContentMD5 header with a
REST PUT request that doesn＇t match the digest calculated on the server you receive a BadDigest
error The error response also includes as detail elements the digest we calculated and the digest
you told us to expect During development you can use this information to diagnose the error In
production a wellbehaved program might include this information in its error log
For information about general response elements go to Error Responses
List of Error Codes
The following table lists Amazon S3 error codes
Error Code Description HTTP
Status
Code
SOAP
Fault
Code
Prefix
AccessDenied Access Denied 403
Forbidden
Client
AccountProblem There is a problem with your AWS
account that prevents the operation
from completing successfully Please
use Contact Us
403
Forbidden
Client
AmbiguousGrantByEmailAddress The email address you provided
is associated with more than one
account
400 Bad
Request
Client
BadDigest The ContentMD5 you specified did
not match what we received
400 Bad
Request
Client
API Version 20060301
8Amazon Simple Storage Service API Reference
List of Error Codes
Error Code Description HTTP
Status
Code
SOAP
Fault
Code
Prefix
BucketAlreadyExists The requested bucket name is not
available The bucket namespace
is shared by all users of the system
Please select a different name and
try again
409
Conflict
Client
BucketAlreadyOwnedByYou Your previous request to create the
named bucket succeeded and you
already own it You get this error
in all AWS regions except US East
(N Virginia) region useast1 In
useast1 region you will get 200
OK but it is noop (if bucket exists it
Amazon S3 will not do anything)
409
Conflict
(in all
regions
except
US
East (N
Virginia)
region)
Client
BucketNotEmpty The bucket you tried to delete is not
empty
409
Conflict
Client
CredentialsNotSupported This request does not support
credentials
400 Bad
Request
Client
CrossLocationLoggingProhibited Crosslocation logging not allowed
Buckets in one geographic location
cannot log information to a bucket in
another location
403
Forbidden
Client
EntityTooSmall Your proposed upload is smaller
than the minimum allowed object
size
400 Bad
Request
Client
EntityTooLarge Your proposed upload exceeds the
maximum allowed object size
400 Bad
Request
Client
ExpiredToken The provided token has expired 400 Bad
Request
Client
IllegalVersioningConfigurationExceptionIndicates that the versioning
configuration specified in the request
is invalid
400 Bad
Request
Client
IncompleteBody You did not provide the number
of bytes specified by the Content
Length HTTP header
400 Bad
Request
Client
IncorrectNumberOfFilesInPostRequestPOST requires exactly one file
upload per request
400 Bad
Request
Client
InlineDataTooLarge Inline data exceeds the maximum
allowed size
400 Bad
Request
Client
InternalError We encountered an internal error
Please try again
500
Internal
Server
Error
Server
API Version 20060301
9Amazon Simple Storage Service API Reference
List of Error Codes
Error Code Description HTTP
Status
Code
SOAP
Fault
Code
Prefix
InvalidAccessKeyId The AWS access key Id you
provided does not exist in our
records
403
Forbidden
Client
InvalidAddressingHeader You must specify the Anonymous
role
NA Client
InvalidArgument Invalid Argument 400 Bad
Request
Client
InvalidBucketName The specified bucket is not valid 400 Bad
Request
Client
InvalidBucketState The request is not valid with the
current state of the bucket
409
Conflict
Client
InvalidDigest The ContentMD5 you specified is
not valid
400 Bad
Request
Client
InvalidEncryptionAlgorithmError The encryption request you specified
is not valid The valid value is
AES256
400 Bad
Request
Client
InvalidLocationConstraint The specified location constraint is
not valid For more information about
regions see How to Select a Region
for Your Buckets
400 Bad
Request
Client
InvalidObjectState The operation is not valid for the
current state of the object
403
Forbidden
Client
InvalidPart One or more of the specified parts
could not be found The part might
not have been uploaded or the
specified entity tag might not have
matched the part＇s entity tag
400 Bad
Request
Client
InvalidPartOrder The list of parts was not in
ascending orderParts list must
specified in order by part number
400 Bad
Request
Client
InvalidPayer All access to this object has been
disabled
403
Forbidden
Client
InvalidPolicyDocument The content of the form does not
meet the conditions specified in the
policy document
400 Bad
Request
Client
InvalidRange The requested range cannot be
satisfied
416
Requested
Range
Not
Satisfiable
Client
API Version 20060301
10Amazon Simple Storage Service API Reference
List of Error Codes
Error Code Description HTTP
Status
Code
SOAP
Fault
Code
Prefix
InvalidRequest Please use AWS4HMACSHA256 400 Bad
Request
NA
InvalidRequest SOAP requests must be made over
an HTTPS connection
400 Bad
Request
Client
InvalidRequest S3 Transfer Acceleration is not
supported for buckets with nonDNS
compliant names
400 Bad
Request
NA
InvalidRequest S3 Transfer Acceleration is not
supported for buckets with periods
() in their names
400 Bad
Request
NA
InvalidRequest S3 Transfer Accelerate endpoint
only supports virtual style requests
400 Bad
Request
NA
InvalidRequest S3 Transfer Accelerate is not
configured on this bucket
400 Bad
Request
NA
InvalidRequest S3 Transfer Accelerate is disabled
on this bucket
400 Bad
Request
NA
InvalidRequest S3 Transfer Acceleration is not
supported on this bucket Contact
AWS Support for more information
400 Bad
Request
NA
InvalidRequest S3 Transfer Acceleration cannot
be enabled on this bucket Contact
AWS Support for more information
400 Bad
Request
NA
InvalidSecurity The provided security credentials are
not valid
403
Forbidden
Client
InvalidSOAPRequest The SOAP request body is invalid 400 Bad
Request
Client
InvalidStorageClass The storage class you specified is
not valid
400 Bad
Request
Client
InvalidTargetBucketForLogging The target bucket for logging does
not exist is not owned by you or
does not have the appropriate grants
for the logdelivery group
400 Bad
Request
Client
InvalidToken The provided token is malformed or
otherwise invalid
400 Bad
Request
Client
InvalidURI Couldn＇t parse the specified URI 400 Bad
Request
Client
KeyTooLong Your key is too long 400 Bad
Request
Client
API Version 20060301
11Amazon Simple Storage Service API Reference
List of Error Codes
Error Code Description HTTP
Status
Code
SOAP
Fault
Code
Prefix
MalformedACLError The XML you provided was not well
formed or did not validate against
our published schema
400 Bad
Request
Client
MalformedPOSTRequest The body of your POST request is
not wellformed multipartformdata
400 Bad
Request
Client
MalformedXML This happens when the user sends
malformed xml (xml that doesn＇t
conform to the published xsd) for the
configuration The error message
is The XML you provided was
not wellformed or did not validate
against our published schema
400 Bad
Request
Client
MaxMessageLengthExceeded Your request was too big 400 Bad
Request
Client
MaxPostPreDataLengthExceededErrorYour POST request fields preceding
the upload file were too large
400 Bad
Request
Client
MetadataTooLarge Your metadata headers exceed the
maximum allowed metadata size
400 Bad
Request
Client
MethodNotAllowed The specified method is not allowed
against this resource
405
Method
Not
Allowed
Client
MissingAttachment A SOAP attachment was expected
but none were found
NA Client
MissingContentLength You must provide the Content
Length HTTP header
411
Length
Required
Client
MissingRequestBodyError This happens when the user sends
an empty xml document as a
request The error message is
Request body is empty
400 Bad
Request
Client
MissingSecurityElement The SOAP 11 request is missing a
security element
400 Bad
Request
Client
MissingSecurityHeader Your request is missing a required
header
400 Bad
Request
Client
NoLoggingStatusForKey There is no such thing as a logging
status subresource for a key
400 Bad
Request
Client
NoSuchBucket The specified bucket does not exist 404 Not
Found
Client
NoSuchKey The specified key does not exist 404 Not
Found
Client
API Version 20060301
12Amazon Simple Storage Service API Reference
List of Error Codes
Error Code Description HTTP
Status
Code
SOAP
Fault
Code
Prefix
NoSuchLifecycleConfiguration The lifecycle configuration does not
exist
404 Not
Found
Client
NoSuchUpload The specified multipart upload does
not exist The upload ID might be
invalid or the multipart upload might
have been aborted or completed
404 Not
Found
Client
NoSuchVersion Indicates that the version ID
specified in the request does not
match an existing version
404 Not
Found
Client
NotImplemented A header you provided implies
functionality that is not implemented
501 Not
Implemented
Server
NotSignedUp Your account is not signed up for
the Amazon S3 service You must
sign up before you can use Amazon
S3 You can sign up at the following
URL httpawsamazoncoms3
403
Forbidden
Client
NoSuchBucketPolicy The specified bucket does not have
a bucket policy
404 Not
Found
Client
OperationAborted A conflicting conditional operation
is currently in progress against this
resource Try again
409
Conflict
Client
PermanentRedirect The bucket you are attempting to
access must be addressed using the
specified endpoint Send all future
requests to this endpoint
301
Moved
Permanently
Client
PreconditionFailed At least one of the preconditions you
specified did not hold
412
Precondition
Failed
Client
Redirect Temporary redirect 307
Moved
Temporarily
Client
RestoreAlreadyInProgress Object restore is already in progress 409
Conflict
Client
RequestIsNotMultiPartContent Bucket POST must be of the
enclosuretype multipartformdata
400 Bad
Request
Client
RequestTimeout Your socket connection to the server
was not read from or written to within
the timeout period
400 Bad
Request
Client
RequestTimeTooSkewed The difference between the request
time and the server＇s time is too
large
403
Forbidden
Client
API Version 20060301
13Amazon Simple Storage Service API Reference
List of Error Codes
Error Code Description HTTP
Status
Code
SOAP
Fault
Code
Prefix
RequestTorrentOfBucketError Requesting the torrent file of a
bucket is not permitted
400 Bad
Request
Client
SignatureDoesNotMatch The request signature we calculated
does not match the signature
you provided Check your AWS
secret access key and signing
method For more information see
REST Authentication and SOAP
Authentication for details
403
Forbidden
Client
ServiceUnavailable Reduce your request rate 503
Service
Unavailable
Server
SlowDown Reduce your request rate 503 Slow
Down
Server
TemporaryRedirect You are being redirected to the
bucket while DNS updates
307
Moved
Temporarily
Client
TokenRefreshRequired The provided token must be
refreshed
400 Bad
Request
Client
TooManyBuckets You have attempted to create more
buckets than allowed
400 Bad
Request
Client
UnexpectedContent This request does not support
content
400 Bad
Request
Client
UnresolvableGrantByEmailAddress The email address you provided
does not match any account on
record
400 Bad
Request
Client
UserKeyMustBeSpecified The bucket POST must contain the
specified field name If it is specified
check the order of the fields
400 Bad
Request
Client
API Version 20060301
14Amazon Simple Storage Service API Reference
Authenticating Requests (AWS
Signature Version 4)
Topics
• Authentication Methods (p 16)
• Introduction to Signing Requests (p 16)
• Authenticating Requests Using the Authorization Header (AWS Signature Version 4) (p 17)
• Authenticating Requests Using Query Parameters (AWS Signature Version 4) (p 38)
• Examples Signature Calculations in AWS Signature Version 4 (p 43)
• Authenticating Requests BrowserBased Uploads Using POST (AWS Signature Version
4) (p 45)
• Amazon S3 Signature Version 4 Authentication Specific Policy Keys (p 47)
Every interaction with Amazon S3 is either authenticated or anonymous This section explains request
authentication with the AWS Signature Version 4 algorithm
Note
If you use the AWS SDKs (see Sample Code and Libraries) to send your requests you don＇t
need to read this section because the SDK clients authenticate your requests by using access
keys that you provide Unless you have a good reason not to you should always use the AWS
SDKs In regions that support both signature versions you can request AWS SDKs to use
specific signature version For more information see Specifying Signature Version in Request
Authentication in the Amazon Simple Storage Service Developer Guide You need to read this
section only if you are implementing the AWS Signature Version 4 algorithm in your custom
client
Authentication with AWS Signature version 4 provides some or all of the following depending on how
you choose to sign your request
• Verification of the identity of the requester – Authenticated requests require a signature that
you create by using your access keys (access key ID secret access key) For information about
getting access keys see Understanding and Getting Your Security Credentials in the AWS General
Reference If you are using temporary security credentials the signature calculations also require
a security token For more information see Requesting Temporary Security Credentials in the IAM
User Guide
• Intransit data protection – In order to prevent tampering with a request while it is in transit you
use some of the request elements to calculate the request signature Upon receiving the request
Amazon S3 calculates the signature by using the same request elements If any request component
API Version 20060301
15Amazon Simple Storage Service API Reference
Authentication Methods
received by Amazon S3 does not match the component that was used to calculate the signature
Amazon S3 will reject the request
• Protect against reuse of the signed portions of the request – The signed portions (using AWS
Signatures) of requests are valid within 15 minutes of the timestamp in the request An unauthorized
party who has access to a signed request can modify the unsigned portions of the request without
affecting the request＇s validity in the 15 minute window Because of this we recommend that you
maximize protection by signing request headers and body making HTTPS requests to Amazon S3
and by using the s3xamzcontentsha256 condition key (see Amazon S3 Signature Version 4
Authentication Specific Policy Keys (p 47)) in AWS policies to require users to sign S3 request
bodies
Note
Amazon S3 supports Signature Version 4 a protocol for authenticating inbound API requests
to AWS services in all AWS regions At this time AWS regions created before January 30
2014 will continue to support the previous protocol Signature Version 2 Any new regions
after January 30 2014 will support only Signature Version 4 and therefore all requests to
those regions must be made with Signature Version 4 For more information about AWS
Signature Version 2 see Signing and Authenticating REST Requests in the Amazon Simple
Storage Service Developer Guide
Authentication Methods
You can express authentication information by using one of the following methods
• HTTP Authorization header – Using the HTTP Authorization header is the most common
method of authenticating an Amazon S3 request All of the Amazon S3 REST operations (except
for browserbased uploads using POST requests) require this header For more information
about the Authorization header value and how to calculate signature and related options see
Authenticating Requests Using the Authorization Header (AWS Signature Version 4) (p 17)
• Query string parameters – You can use a query string to express a request entirely in a URL In
this case you use query parameters to provide request information including the authentication
information Because the request signature is part of the URL this type of URL is often referred to as
a presigned URL You can use presigned URLs to embed clickable links which can be valid for up to
seven days in HTML For more information see Authenticating Requests Using Query Parameters
(AWS Signature Version 4) (p 38)
Amazon S3 also supports browserbased uploads that use an HTTP POST requests With an HTTP
POST request you can upload content to Amazon S3 directly from the browser For information about
authenticating POST requests see BrowserBased Uploads Using POST in the Amazon Simple
Storage Service Developer Guide
Introduction to Signing Requests
Authentication information that you send in a request must include a signature To calculate a
signature you first concatenate select request elements to form a string referred to as the string to
sign You then use a signing key to calculate the hashbased message authentication code (HMAC) of
the string to sign
In AWS Signature Version 4 you don＇t use your secret access key to sign the request Instead you
first use your secret access key to create a signing key The signing key is scoped to a specific region
and service and it never expires
API Version 20060301
16Amazon Simple Storage Service API Reference
Using an Authorization Header
The following diagram illustrates the general process of computing a signature
The string to sign depends on the request type For example when you use the HTTP Authorization
header or the query parameters for authentication you use a varying combination of request elements
to create the string to sign For an HTTP POST request the POST policy in the request is the string
you sign
Upon receiving an authenticated request Amazon S3 servers recreate the signature by using the
authentication information that is contained in the request If the signatures match Amazon S3
processes your request otherwise the request is rejected
For more information about authenticating requests see the following topics
• Authenticating Requests Using the Authorization Header (AWS Signature Version 4) (p 17)
• Authenticating Requests Using Query Parameters (AWS Signature Version 4) (p 38)
• Authenticating Requests in BrowserBased Uploads Using POST (AWS Signature Version
4) (p 52)
Authenticating Requests Using the Authorization
Header (AWS Signature Version 4)
Topics
• Overview (p 17)
• Signature Calculations for the Authorization Header Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p 20)
• Signature Calculations for the Authorization Header Transferring Payload in Multiple Chunks
(Chunked Upload) (AWS Signature Version 4) (p 31)
Overview
Using the HTTP Authorization header is the most common method of providing authentication
information Except for POST requests (p 279) and requests that are signed by using query
parameters all Amazon S3 bucket operations (p 70) and object operations (p 238) use the
Authorization request header to provide authentication information
The following is an example of the Authorization header value Line breaks are added to this
example for readability
Authorization AWS4HMACSHA256
API Version 20060301
17Amazon Simple Storage Service API Reference
Overview
CredentialAKIAIOSFODNN7EXAMPLE20130524useast1s3aws4_request
SignedHeadershostrangexamzdate
Signaturefe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024
The following is the properly formatted version of the same Authorization header
Note the following
• There is space between the first two components AWS4HMACSHA256 and Credential
• The subsequent components Credential SignedHeaders and Signature are separated by a
comma
The following table describes the various components of the Authorization header value in the
preceding example
Component Description
AWS4HMACSHA256 The algorithm that was used to calculate the signature You must
provide this value when you use AWS Signature Version 4 for
authentication
The string specifies AWS Signature Version 4 (AWS4) and the
signing algorithm (HMACSHA256)
Credential Your access key ID and the scope information which includes the
date region and service that were used to calculate the signature
This string has the following form
service>aws4_request
Where
• value is specified using YYYYMMDD format
• value is s3 when sending request to Amazon
S3
SignedHeaders A semicolonseparated list of request headers that you used to
compute Signature The list includes header names only and
the header names must be in lowercase For example
hostrangexamzdate
Signature The 256bit signature expressed as 64 lowercase hexadecimal
characters For example
fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024
Note that the signature calculations vary depending on the option
you choose to transfer the payload
The signature calculations vary depending on the method you choose to transfer the request payload
S3 supports the following options
API Version 20060301
18Amazon Simple Storage Service API Reference
Overview
• Transfer payload in a single chunk – In this case you have the following signature calculation
options
• Signed payload option – You can optionally compute the entire payload checksum and include it
in signature calculation This provides added security but you need to read your payload twice or
buffer it in memory
For example in order to upload a file you need to read the file first to compute a payload hash
for signature calculation and again for transmission when you create the request For smaller
payloads this approach might be preferable However for large files reading the file twice can be
inefficient so you might want to upload data in chunks instead
We recommend you include payload checksum for added security
• Unsigned payload option – Do not include payload checksum in signature calculation
For stepbystep instructions to calculate signature and construct the Authorization header value see
Signature Calculations for the Authorization Header Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p 20)
• Transfer payload in multiple chunks (chunked upload) – In this case you transfer payload in
chunks You can transfer a payload in chunks regardless of the payload size
You can break up your payload into chunks These can be fixed or variablesize chunks By
uploading data in chunks you avoid reading the entire payload to calculate the signature Instead
for the first chunk you calculate a seed signature that uses only the request headers The second
chunk contains the signature for the first chunk and each subsequent chunk contains the signature
for the chunk that precedes it At the end of the upload you send a final chunk with 0 bytes of data
that contains the signature of the last chunk of the payload For more information see Signature
Calculations for the Authorization Header Transferring Payload in Multiple Chunks (Chunked
Upload) (AWS Signature Version 4) (p 31)
When you send a request you must tell Amazon S3 which of the preceding options you have chosen
in your signature calculation by adding the xamzcontentsha256 header with one of the following
values
• If you choose chunked upload options set the header value to STREAMINGAWS4HMACSHA256
PAYLOAD
• If you choose to upload payload in a single chunk set the header value to the payload checksum
(signed payload option) or set the value to the literal string UNSIGNEDPAYLOAD (unsigned payload
option)
Upon receiving the request Amazon S3 recreates the string to sign using information in the
Authorization header and the date header It then verifies with authentication service the
signatures match The request date can be specified by using either the HTTP Date or the xamz
date header If both headers are present xamzdate takes precedence
If the signatures match Amazon S3 processes your request otherwise your request will fail
For more information see the following topics
Signature Calculations for the Authorization Header Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p 20)
Signature Calculations for the Authorization Header Transferring Payload in Multiple Chunks
(Chunked Upload) (AWS Signature Version 4) (p 31)
API Version 20060301
19Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in a Single Chunk
Signature Calculations for the Authorization Header
Transferring Payload in a Single Chunk (AWS
Signature Version 4)
When using the Authorization header to authenticate requests the header value includes among
other things a signature The signature calculations vary depending on the choice you make for
transferring the payload (Overview (p 17)) This section explains signature calculations when you
choose to transfer the payload in a single chunk The example section (see Examples Signature
Calculations (p 25)) shows signature calculations and resulting Authorization headers that you
can use as a test suite to verify your code
Important
When transferring payload in a single chunk you can optionally choose to include the payload
hash in the signature calculations referred as signed payload (if you don＇t include it the
payload is considered unsigned) The signing procedure discussed in the following section
applies to both but note the following differences
• Signed payload option – You include the payload hash when constructing the canonical
request (that then becomes part of StringToSign as explained in the signature calculation
section) You also specify the same value as the xamzcontentsha256 header value
when sending the request to S3
• Unsigned payload option – You include the literal string UNSIGNEDPAYLOAD when
constructing a canonical request and set the same value as the he xamzcontent
sha256 header value when sending the request to S3
When you send your request to S3 the xamzcontentsha256 header value informs S3
whether the payload is signed or not Amazon S3 can then create signature accordingly for
verification
Calculating a Signature
To calculate a signature you first need a string to sign You then calculate a HMACSHA256 hash of
the string to sign by using a signing key The following diagram illustrates the process including the
various components of the string that you create for signing
When Amazon S3 receives an authenticated request it computes the signature and then compares it
with the signature that you provided in the request For that reason you must compute the signature
by using the same method that is used by Amazon S3 The process of putting a request in an agreed
upon form for signing is called canonicalization
API Version 20060301
20Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in a Single Chunk
The following table describes the functions that are shown in the diagram You need to implement code
for these functions
Function Description
Lowercase() Convert the string to lowercase
Hex() Lowercase base 16 encoding
SHA256Hash() Secure Hash Algorithm (SHA) cryptographic hash function
HMACSHA256() Computes HMAC by using the SHA256 algorithm with the signing
key provided This is the final signature
Trim() Remove any leading or trailing whitespace
UriEncode() URI encode every byte UriEncode() must enforce the following
rules
• URI encode every byte except the unreserved characters ＇A＇＇Z＇
＇a＇＇z＇ ＇0＇＇9＇ ＇＇ ＇＇ ＇_＇ and ＇~＇
• The space character is a reserved character and must be
encoded as 20 (and not as +)
• Each URI encoded byte is formed by a ＇＇ and the twodigit
hexadecimal value of the byte
• Letters in the hexadecimal value must be uppercase for
example 1A
• Encode the forward slash character ＇＇ everywhere except in
the object key name For example if the object key name is
photosJansamplejpg the forward slash in the key name
is not encoded
API Version 20060301
21Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in a Single Chunk
Function Description
Caution
The standard UriEncode functions provided by your
development platform may not work because of
differences in implementation and related ambiguity in the
underlying RFCs We recommend that you write your own
custom UriEncode function to ensure that your encoding
will work
The following is an example uriencode() function in Java
public static String UriEncode(CharSequence input
boolean encodeSlash) {
StringBuilder result new
StringBuilder()
for (int i 0 i < inputlength() i++)
{
char ch inputcharAt(i)
if ((ch > ＇A＇ && ch < ＇Z＇) || (ch
> ＇a＇ && ch < ＇z＇) || (ch > ＇0＇ && ch < ＇9＇)
|| ch ＇_＇ || ch ＇＇ || ch ＇~＇ || ch
＇＇) {
resultappend(ch)
} else if (ch ＇＇) {
resultappend(encodeSlash
2F ch)
} else {
resultappend(toHexUTF8(ch))
}
}
return resulttoString()
}
Task 1 Create a Canonical Request
This section provides an overview of creating a canonical request
The following is the canonical request format that Amazon S3 uses to calculate a signature For
signatures to match you must create a canonical request in this format
＼n
＼n
＼n
＼n
＼n
Where
• HTTPMethod is one of the HTTP methods for example GET PUT HEAD and DELETE
• CanonicalURI is the URIencoded version of the absolute path component of the URI—everything
starting with the that follows the domain name and up to the end of the string or to the question
mark character (＇＇) if you have query string parameters The URI in the following example
examplebucketmyphotojpg is the absolute path and you don＇t encode the in the absolute
path
API Version 20060301
22Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in a Single Chunk
https3amazonawscomexamplebucketmyphotojpg
Note
You do not normalize URI paths for requests to Amazon S3 For example you may have
a bucket with an object named myobjectexamplephotouser Normalizing the path
changes the object name in the request to myobjectexamplephotouser This is an
incorrect path for that object
• CanonicalQueryString specifies the URIencoded query string parameters You URIencode
name and values individually You must also sort the parameters in the canonical query string
alphabetically by key name The sorting occurs after encoding The query string in the following URI
example is prefixsomePrefix&markersomeMarker&maxkeys20
https3amazonawscomexamplebucket
prefixsomePrefix&markersomeMarker&maxkeys20
The canonical query string is as follows (line breaks are added to this example for readability)
URIencode(marker)++URIencode(someMarker)+&+
URIencode(maxkeys)++URIencode(20) + & +
URIencode(prefix)++URIencode(somePrefix)
When a request targets a subresource the corresponding query parameter value will be an empty
string () For example the following URI identifies the ACL subresource on the examplebucket
bucket
https3amazonawscomexamplebucketacl
The CanonicalQueryString in this case is as follows
URIencode(acl) + +
If the URI does not include a ＇＇ there is no query string in the request and you set the canonical
query string to an empty string () You will still need to include the ＼n
• CanonicalHeaders is a list of request headers with their values Individual header name and value
pairs are separated by the newline character (＼n) Header names must be in lowercase You must
sort the header names alphabetically to construct the string as shown in the following example
Lowercase()++Trim()+＼n
Lowercase()++Trim()+＼n
Lowercase()++Trim()+＼n
The Lowercase() and Trim() functions used in this example are described in the preceding
section
The CanonicalHeaders list must include the following
• HTTP host header
• If the ContentType header is present in the request you must add it to the
CanonicalHeaders list
API Version 20060301
23Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in a Single Chunk
• Any xamz* headers that you plan to include in your request must also be added For example
if you are using temporary security credentials you need to include xamzsecuritytoken in
your request You must add this header in the list of CanonicalHeaders
Note
The xamzcontentsha256 header is required for all AWS Signature Version 4
requests It provides a hash of the request payload If there is no payload you must provide
the hash of an empty string
The following is an example CanonicalHeaders string The header names are in lowercase and
sorted
hosts3amazonawscom
xamzcontent
sha256e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b785
2b855
xamzdate20130708T220855Z
Note
For the purpose of calculating an authorization signature only the host and any xamz
* headers are required however in order to prevent data tampering you should consider
including all the headers in the signature calculation
• SignedHeaders is an alphabetically sorted semicolonseparated list of lowercase request
header names The request headers in the list are the same headers that you included in the
CanonicalHeaders string For example for the previous example the value of SignedHeaders
would be as follows
hostxamzcontentsha256xamzdate
• HashedPayload is the hexadecimal value of the SHA256 hash of the request payload
Hex(SHA256Hash()
If there is no payload in the request you compute a hash of the empty string as follows
Hex(SHA256Hash())
The hash returns the following value
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
For example when you upload an object by using a PUT request you provide object data in the
body When you retrieve an object by using a GET request you compute the empty string hash
Task 2 Create a String to Sign
This section provides an overview of creating a string to sign For stepbystep instructions see Task 2
Create a String to Sign in the AWS General Reference
The string to sign is a concatenation of the following strings
AWS4HMACSHA256 + ＼n +
timeStampISO8601Format + ＼n +
+ ＼n +
API Version 20060301
24Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in a Single Chunk
Hex(SHA256Hash())
The constant string AWS4HMACSHA256 specifies the hash algorithm that you are using
HMACSHA256 The timeStamp is the current UTC time in ISO 8601 format (for example
20130524T000000Z)
Scope binds the resulting signature to a specific date an AWS region and a service Thus your
resulting signature will work only in the specific region and for a specific service The signature is valid
for seven days after the specified date
dateFormat() + + + + + aws4_request
For Amazon S3 the service string is s3 For a list of region strings see Regions and Endpoints in the
AWS General Reference The region column in this table provides the list of valid region strings
The following scope restricts the resulting signature to the useast1 region and Amazon S3
20130606useast1s3aws4_request
Note
Scope must use the same date that you use to compute the signing key as discussed in the
following section
Task 3 Calculate Signature
In AWS Signature Version 4 instead of using your AWS access keys to sign a request you first create
a signing key that is scoped to a specific region and service For more information about signing keys
see Introduction to Signing Requests (p 16)
DateKey HMACSHA256(AWS4+ )
DateRegionKey HMACSHA256( )
DateRegionServiceKey HMACSHA256( )
SigningKey HMACSHA256( aws4_request)
Note
This signing key is valid for seven days from the date specified in the DateKey hash
For a list of region strings see Regions and Endpoints in the AWS General Reference
Using a signing key enables you to keep your AWS credentials in one safe place For example if you
have multiple servers that communicate with Amazon S3 you share the signing key with those servers
you don’t have to keep a copy of your secret access key on each server Signing key is valid for up to
seven days So each time you calculate signing key you will need to share the signing key with your
servers For more information see Authenticating Requests (AWS Signature Version 4) (p 15)
The final signature is the HMACSHA256 hash of the string to sign using the signing key as the key
HMACSHA256(SigningKey StringToSign)
For stepbystep instructions on creating a signature see Task 3 Create a Signature in the AWS
General Reference
Examples Signature Calculations
You can use the examples in this section as a reference to check signature calculations in your code
For additional references see Signature Version 4 Test Suite of the AWS General Reference The
calculations shown in the examples use the following data
API Version 20060301
25Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in a Single Chunk
• Example access keys
Parameter Value
AWSAccessKeyId AKIAIOSFODNN7EXAMPLE
AWSSecretAccessKey wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
• Request timestamp of 20130524T000000Z (Fri 24 May 2013 000000 GMT)
• Bucket name examplebucket
• The bucket is assumed to be in the US East (N Virginia) region The credential Scope and the
Signing Key calculations use useast1 as the region specifier For information about other
regions see Regions and Endpoints in the AWS General Reference
• You can use either pathstyle or virtual hosted–style requests The following examples show how to
sign a virtual hosted–style request for example
httpsexamplebuckets3amazonawscomphotosphoto1jpg
For more information see Virtual Hosting of Buckets in the Amazon Simple Storage Service
Developer Guide
Example GET Object
The following example gets the first 10 bytes of an object (testtxt) from examplebucket For more
information about the API action see GET Object (p 251)
GET testtxt HTTP11
Host examplebuckets3amazonawscom
xamzdate20130524T000000Z
Authorization SignatureToBeCalculated
Range bytes09
xamzcontent
sha256e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
xamzdate 20130524T000000Z
Because this GET request does not provide any body content the xamzcontentsha256 value is
the hash of the empty request body The following steps show signature calculations and construction
of the Authorization header
1 StringToSign
a CanonicalRequest
GET
testtxt
hostexamplebuckets3amazonawscom
rangebytes09
xamzcontent
sha256e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
xamzdate20130524T000000Z
hostrangexamzcontentsha256xamzdate
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
API Version 20060301
26Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in a Single Chunk
In the canonical request string the last line is the hash of the empty request body The third
line is empty because there are no query parameters in the request
b StringToSign
AWS4HMACSHA256
20130524T000000Z
20130524useast1s3aws4_request
7344ae5b7ee6c3e7e6b0fe0640412a37625d1fbfff95c48bbb2dc43964946972
2 SigningKey
signing key HMACSHA256(HMACSHA256(HMACSHA256(HMACSHA256(AWS4 +
20130524)useast1)s3)aws4_request)
3 Signature
f0e8bdb87c964420e857bd35b5d6ed310bd44f0170aba48dd91039c6036bdb41
4 Authorization header
The resulting Authorization header is as follows
AWS4HMACSHA256 CredentialAKIAIOSFODNN7EXAMPLE20130524useast1
s3aws4_requestSignedHeadershostrangexamzcontentsha256xamz
dateSignaturef0e8bdb87c964420e857bd35b5d6ed310bd44f0170aba48dd91039c6036bdb41
Example PUT Object
This example PUT request creates an object (testfiletext) in examplebucket The example
assumes the following
• You are requesting REDUCED_REDUNDANCY as the storage class by adding the xamzstorage
class request header For information about storage classes see Storage Classes in the Amazon
Simple Storage Service Developer Guide
• The content of the uploaded file is a string Welcome to Amazon S3 The value of xamz
contentsha256 in the request is based on this string
For information about the API action see PUT Object (p 291)
PUT testfiletext HTTP11
Host examplebuckets3amazonawscom
Date Fri 24 May 2013 000000 GMT
Authorization SignatureToBeCalculated
xamzdate 20130524T000000Z
xamzstorageclass REDUCED_REDUNDANCY
xamzcontentsha256
44ce7dd67c959e0d3524ffac1771dfbba87d2b6b4b4e99e42034a8b803f8b072
The following steps show signature calculations
API Version 20060301
27Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in a Single Chunk
1 StringToSign
a CanonicalRequest
PUT
test24filetext
dateFri 24 May 2013 000000 GMT
hostexamplebuckets3amazonawscom
xamzcontent
sha25644ce7dd67c959e0d3524ffac1771dfbba87d2b6b4b4e99e42034a8b803f8b072
xamzdate20130524T000000Z
xamzstorageclassREDUCED_REDUNDANCY
datehostxamzcontentsha256xamzdatexamzstorageclass
44ce7dd67c959e0d3524ffac1771dfbba87d2b6b4b4e99e42034a8b803f8b072
In the canonical request the third line is empty because there are no query parameters in the
request The last line is the hash of the body which should be same as the xamzcontent
sha256 header value
b StringToSign
AWS4HMACSHA256
20130524T000000Z
20130524useast1s3aws4_request
9e0e90d9c76de8fa5b200d8c849cd5b8dc7a3be3951ddb7f6a76b4158342019d
2 SigningKey
signing key HMACSHA256(HMACSHA256(HMACSHA256(HMACSHA256(AWS4 +
20130524)useast1)s3)aws4_request)
3 Signature
98ad721746da40c64f1a55b78f14c238d841ea1380cd77a1b5971af0ece108bd
4 Authorization header
The resulting Authorization header is as follows
AWS4HMACSHA256 CredentialAKIAIOSFODNN7EXAMPLE20130524
useast1s3aws4_requestSignedHeadersdatehostx
amzcontentsha256xamzdatexamzstorage
classSignature98ad721746da40c64f1a55b78f14c238d841ea1380cd77a1b5971af0ece108bd
Example GET Bucket Lifecycle
The following GET request retrieves the lifecycle configuration of examplebucket For information
about the API action see GET Bucket lifecycle (p 113)
GET lifecycle HTTP11
Host examplebuckets3amazonawscom
Authorization SignatureToBeCalculated
xamzdate 20130524T000000Z
API Version 20060301
28Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in a Single Chunk
xamzcontent
sha256e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Because the request does not provide any body content the xamzcontentsha256 header value
is the hash of the empty request body The following steps show signature calculations
1 StringToSign
a CanonicalRequest
GET
lifecycle
hostexamplebuckets3amazonawscom
xamzcontent
sha256e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
xamzdate20130524T000000Z
hostxamzcontentsha256xamzdate
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
In the canonical request the last line is the hash of the empty request body
b StringToSign
AWS4HMACSHA256
20130524T000000Z
20130524useast1s3aws4_request
9766c798316ff2757b517bc739a67f6213b4ab36dd5da2f94eaebf79c77395ca
2 SigningKey
signing key HMACSHA256(HMACSHA256(HMACSHA256(HMACSHA256(AWS4 +
20130524)useast1)s3)aws4_request)
3 Signature
fea454ca298b7da1c68078a5d1bdbfbbe0d65c699e0f91ac7a200a0136783543
4 Authorization header
The resulting Authorization header is as follows
AWS4HMACSHA256 CredentialAKIAIOSFODNN7EXAMPLE20130524useast1
s3aws4_requestSignedHeadershostxamzcontentsha256xamz
dateSignaturefea454ca298b7da1c68078a5d1bdbfbbe0d65c699e0f91ac7a200a0136783543
Example Get Bucket (List Objects)
The following example retrieves a list of objects from examplebucket bucket For information about
the API action see GET Bucket (List Objects) Version 1 (p 96)
GET maxkeys2&prefixJ HTTP11
Host examplebuckets3amazonawscom
Authorization SignatureToBeCalculated
xamzdate 20130524T000000Z
API Version 20060301
29Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in a Single Chunk
xamzcontent
sha256e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Because the request does not provide a body the value of xamzcontentsha256 is the hash of
the empty request body The following steps show signature calculations
1 StringToSign
a CanonicalRequest
GET
maxkeys2&prefixJ
hostexamplebuckets3amazonawscom
xamzcontent
sha256e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
xamzdate20130524T000000Z
hostxamzcontentsha256xamzdate
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
In the canonical string the last line is the hash of the empty request body
b StringToSign
AWS4HMACSHA256
20130524T000000Z
20130524useast1s3aws4_request
df57d21db20da04d7fa30298dd4488ba3a2b47ca3a489c74750e0f1e7df1b9b7
2 SigningKey
signing key HMACSHA256(HMACSHA256(HMACSHA256(HMACSHA256(AWS4 +
20130524)useast1)s3)aws4_request)
3 Signature
34b48302e7b5fa45bde8084f4b7868a86f0a534bc59db6670ed5711ef69dc6f7
4 Authorization header
The resulting Authorization header is as follows
AWS4HMACSHA256 CredentialAKIAIOSFODNN7EXAMPLE20130524useast1
s3aws4_requestSignedHeadershostxamzcontentsha256xamz
dateSignature34b48302e7b5fa45bde8084f4b7868a86f0a534bc59db6670ed5711ef69dc6f7
API Version 20060301
30Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in Multiple Chunks
Signature Calculations for the Authorization Header
Transferring Payload in Multiple Chunks (Chunked
Upload) (AWS Signature Version 4)
As described in the Overview (p 17) when authenticating requests using the Authorization header
you have an option of uploading the payload in chunks You can send data in fixed size or variable size
chunks This section describes the signature calculation process in chunked upload how you create
the chunk body and how the delayed signing works where you first upload the chunk and send its
signature in the subsequent chunk The example section (see Example PUT Object (p 35)) shows
signature calculations and resulting Authorization headers that you can use as test suite to verify
your code
Note
When transferring data in a series of chunks you must use the ContentLength HTTP
header to explicitly specify the total content length (object length in bytes plus metadata in
each chunk) This will require you to precompute the total length of the payload including the
metadata you will send in each chunk before starting your request The xamzdecoded
contentlength header will contain the size of the object length in bytes
Each chunk signature calculation includes the signature of the previous chunk To begin with you
create a seed signature using only the headers You use the seed signature in the signature calculation
of the first chunk For each subsequent chunk you create a chunk signature that includes signature of
the previous chunk Thus the chunk signatures are chained together that is signature of chunk n is a
function F(chunk n signature(chunk n1)) The chaining ensures you send the chunks in correct order
To perform a chunked upload do the following
1 Decide payload chunk size You need this when you write the code
Chunk size must be at least 8 KB We recommend a chunk size of a least 64 KB for better
performance This chunk size applies to all chunk except the last one The last chunk you send can
be smaller than 8 KB If your payload is small and can fit in one chunk then it can be smaller than
the 8 KB
2 Create the seed signature for inclusion in the first chunk For more information see Calculating the
Seed Signature (p 31)
3 Create the first chunk and stream it For more information see Defining the Chunk Body (p 34)
4 For each subsequent chunk calculate the chunk signature that includes the previous signature in
the string you sign construct the chunk and send it For more information see Defining the Chunk
Body (p 34)
5 Send the final additional chunk same as other chunks in construction but it has zero data bytes
For more information see Defining the Chunk Body (p 34)
Calculating the Seed Signature
The following diagram illustrates the process of calculating the seed signature
API Version 20060301
31Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in Multiple Chunks
The following table describes the functions that are shown in the diagram You need to implement code
for these functions
Function Description
Lowercase() Convert the string to lowercase
Hex() Lowercase base 16 encoding
SHA256Hash() Secure Hash Algorithm (SHA) cryptographic hash function
HMACSHA256() Computes HMAC by using the SHA256 algorithm with the signing
key provided This is the final signature
Trim() Remove any leading or trailing whitespace
UriEncode() URI encode every byte UriEncode() must enforce the following
rules
• URI encode every byte except the unreserved characters ＇A＇＇Z＇
＇a＇＇z＇ ＇0＇＇9＇ ＇＇ ＇＇ ＇_＇ and ＇~＇
• The space character is a reserved character and must be
encoded as 20 (and not as +)
• Each URI encoded byte is formed by a ＇＇ and the twodigit
hexadecimal value of the byte
• Letters in the hexadecimal value must be uppercase for
example 1A
• Encode the forward slash character ＇＇ everywhere except in
the object key name For example if the object key name is
photosJansamplejpg the forward slash in the key name
is not encoded
API Version 20060301
32Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in Multiple Chunks
Function Description
Caution
The standard UriEncode functions provided by your
development platform may not work because of
differences in implementation and related ambiguity in the
underlying RFCs We recommend that you write your own
custom UriEncode function to ensure that your encoding
will work
The following is an example uriencode() function in Java
public static String UriEncode(CharSequence input
boolean encodeSlash) {
StringBuilder result new
StringBuilder()
for (int i 0 i < inputlength() i++)
{
char ch inputcharAt(i)
if ((ch > ＇A＇ && ch < ＇Z＇) || (ch
> ＇a＇ && ch < ＇z＇) || (ch > ＇0＇ && ch < ＇9＇)
|| ch ＇_＇ || ch ＇＇ || ch ＇~＇ || ch
＇＇) {
resultappend(ch)
} else if (ch ＇＇) {
resultappend(encodeSlash
2F ch)
} else {
resultappend(toHexUTF8(ch))
}
}
return resulttoString()
}
For information about the signing process see Signature Calculations for the Authorization Header
Transferring Payload in a Single Chunk (AWS Signature Version 4) (p 20) The process is the same
except that the creation of CanonicalRequest differs as follows
• In addition to the request headers you plan to add you must include the following headers
Header Description
xamzcontent
sha256
This header is required for all AWS Signature Version 4 requests Set the
value to STREAMINGAWS4HMACSHA256PAYLOAD to indicate that the
signature covers only headers and that there is no payload
API Version 20060301
33Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in Multiple Chunks
Header Description
ContentEncoding Set the value to awschunked
Amazon S3 supports multiple content encodings For example
ContentEncoding awschunkedgzip
That is you can specify your custom contentencoding when using
Signature Version 4 streaming API
Note
S3 will store the resulting object without the awschunked
encoding Therefore when you retrieve the object it will not be
awschunked encoded
xamzdecoded
contentlength
Set the value to the length in bytes of the data to be chunked without
counting any metadata For example if you are uploading a 4 GB file set
the value to 4294967296
ContentLength Set the value to the length of your data including the metadata Each
chunk will have metadata such as the signature of the previous chunk
Chunk calculations are discussed in the following section
You send the first chunk with the seed signature You will need to construct the chunk as described in
the following section
Defining the Chunk Body
All chunks include some metadata Each chunk must conform to the following structure
string(IntHexBase(chunksize)) + chunksignature + signature + ＼r＼n
+ chunkdata + ＼r＼n
Where
• IntHexBase() is a function that you will write to convert an integer chunksize to hexadecimal For
example if chunksize is 65536 hexadecimal string is 1000
• chunksize is the size in bytes of the chunkdata without metadata For example if you are
uploading a 65 KB object and using a chunk size of 64 KB you upload the data in three chunks the
first would be 64 KB the second 1 KB and the final chunk with 0 bytes
• signature For each chunk you calculate signature using the following string to sign For the first
chunk you use the seedsignature as the previous signature
API Version 20060301
34Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in Multiple Chunks
The size of the final chunk data that you send is 0 although the chunk body will still contain metadata
including the signature of the previous chunk
Example PUT Object
You can use the examples in this section as a reference to check signature calculations in your code
Before you review the examples note the following
• The signature calculations in these examples use the following example security credentials
Parameter Value
AWSAccessKeyId AKIAIOSFODNN7EXAMPLE
AWSSecretAccessKey wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
• All examples use the request timestamp 20130524T000000Z (Fri 24 May 2013 000000
GMT)
• All examples use examplebucket as the bucket name
• The bucket is assumed to be in the US East (N Virginia) region and the credential Scope and the
Signing Key calculations use useast1 as the region specifier For more information see
Regions and Endpoints in the Amazon Web Services General Reference
• You can use either path style or virtualhosted style requests The examples below show use virtual
hosted style requests for example
httpsexamplebuckets3amazonawscomphotosphoto1jpg
For more information see Virtual Hosting of Buckets in the Amazon Simple Storage Service
Developer Guide
Example PUT Object
The following example sends a PUT request to upload an object The signature calculations assume
the following
• You are uploading a 65 KB text file and the file content is a onecharacter string made up of the
letter ＇a＇
• The chunk size is 64 KB As a result the payload will be uploaded in three chunks 64 KB 1 KB and
the final chunk with 0 bytes of chunk data
API Version 20060301
35Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in Multiple Chunks
• The resulting object has the key name chunkObjecttxt
• You are requesting REDUCED_REDUNDANCY as the storage class by adding the xamzstorage
class request header
For information about the API action see PUT Object (p 291) The general request syntax is as
follows
PUT examplebucketchunkObjecttxt HTTP11
Host s3amazonawscom
xamzdate 20130524T000000Z
xamzstorageclass REDUCED_REDUNDANCY
Authorization SignatureToBeCalculated
xamzcontentsha256 STREAMINGAWS4HMACSHA256PAYLOAD
ContentEncoding awschunked
xamzdecodedcontentlength 66560
ContentLength 66824
The following steps show signature calculations
1 Seed signature — Create String to Sign
1 CanonicalRequest
PUT
examplebucketchunkObjecttxt
contentencodingawschunked
contentlength66824
hosts3amazonawscom
xamzcontentsha256STREAMINGAWS4HMACSHA256PAYLOAD
xamzdate20130524T000000Z
xamzdecodedcontentlength66560
xamzstorageclassREDUCED_REDUNDANCY
contentencodingcontentlengthhostxamzcontentsha256xamz
datexamzdecodedcontentlengthxamzstorageclass
STREAMINGAWS4HMACSHA256PAYLOAD
In the canonical request the third line is empty because there are no query parameters in the
request The last line is the constant string provided as the value of the hashed Payload which
should be same as the value of xamzcontentsha256 header
2 StringToSign
AWS4HMACSHA256
20130524T000000Z
20130524useast1s3aws4_request
cee3fed04b70f867d036f722359b0b1f2f0e5dc0efadbc082b76c4c60e316455
Note
For information about each of line in the string to sign see the diagram that explains
seed signature calculation
API Version 20060301
36Amazon Simple Storage Service API Reference
Signature Calculation Transfer
Payload in Multiple Chunks
2 SigningKey
signing key HMACSHA256(HMACSHA256(HMACSHA256(HMACSHA256(AWS4 +
20130524)useast1)s3)aws4_request)
3 Seed Signature
4f232c4386841ef735655705268965c44a0e4690baa4adea153f7db9fa80a0a9
4 Authorization header
The resulting Authorization header is as follows
AWS4HMACSHA256 CredentialAKIAIOSFODNN7EXAMPLE20130524useast1s3
aws4_requestSignedHeaderscontentencodingcontentlengthhostxamz
contentsha256xamzdatexamzdecodedcontentlengthxamzstorage
classSignature4f232c4386841ef735655705268965c44a0e4690baa4adea153f7db9fa80a0a9
5 Chunk 1 (65536 bytes with value 97 for letter ＇a＇)
1 Chunk string to sign
AWS4HMACSHA256PAYLOAD
20130524T000000Z
20130524useast1s3aws4_request
4f232c4386841ef735655705268965c44a0e4690baa4adea153f7db9fa80a0a9
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
bf718b6f653bebc184e1479f1935b8da974d701b893afcf49e701f3e2f9f9c5a
Note
To information about each line in the string to sign see the preceding diagram that
show various components of the string to sign (for example the last three lines are
previoussignature hash() and hash(currentchunkdata))
2 Chunk signature
ad80c730a21e5b8d04586a2213dd63b9a0e99e0e2307b0ade35a65485a288648
3 Chunk data sent
10000chunk
signaturead80c730a21e5b8d04586a2213dd63b9a0e99e0e2307b0ade35a65485a288648
<65536bytes>
6 Chunk 2 (1024 bytes with value 97 for letter ＇a＇)
1 Chunk string to sign
AWS4HMACSHA256PAYLOAD
20130524T000000Z
20130524useast1s3aws4_request
ad80c730a21e5b8d04586a2213dd63b9a0e99e0e2307b0ade35a65485a288648
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
2edc986847e209b4016e141a6dc8716d3207350f416969382d431539bf292e4a
2 Chunk signature
API Version 20060301
37Amazon Simple Storage Service API Reference
Using Query Parameters
0055627c9e194cb4542bae2aa5492e3c1575bbb81b612b7d234b86a503ef5497
3 Chunk data sent
400chunk
signature0055627c9e194cb4542bae2aa5492e3c1575bbb81b612b7d234b86a503ef5497
<1024 bytes>
7 Chunk 3 (0 byte data)
1 Chunk string to sign
AWS4HMACSHA256PAYLOAD
20130524T000000Z
20130524useast1s3aws4_request
0055627c9e194cb4542bae2aa5492e3c1575bbb81b612b7d234b86a503ef5497
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
2 Chunk signature
b6c6ea8a5354eaf15b3cb7646744f4275b71ea724fed81ceb9323e279d449df9
3 Chunk data sent
0chunk
signatureb6c6ea8a5354eaf15b3cb7646744f4275b71ea724fed81ceb9323e279d449df9
Authenticating Requests Using Query
Parameters (AWS Signature Version 4)
As described in the authentication overview (see Authentication Methods (p 16)) you can provide
authentication information using query string parameters Using query parameters to authenticate
requests is useful when you want to express a request entirely in a URL This method is also referred
as presigning a URL
A use case scenario for presigned URLs is that you can grant temporary access to your Amazon S3
resources For example you can embed a presigned URL on your website or alternatively use it in
command line client (such as Curl) to download objects
The following is an example presigned URL
httpss3amazonawscomexamplebuckettesttxt
XAmzAlgorithmAWS4HMACSHA256
&XAmzCredential20130721useast1s3aws4_request
&XAmzDate20130721T201207Z
&XAmzExpires86400
&XAmzSignedHeadershost
&XAmzSignature
In the example URL note the following
API Version 20060301
38Amazon Simple Storage Service API Reference
Using Query Parameters
• The line feeds are added for readability
• The XAmzCredential value in the URL shows the character only for readability In practice it
should be encoded as 2F For example
&XAmzCredential2F201307212Fus
east12Fs32Faws4_request
The following table describes the query parameters in the URL that provide authentication information
Query String Parameter
Name
Example Value
XAmzAlgorithm Identifies the version of AWS Signature and the algorithm that you
used to calculate the signature
For AWS Signature Version 4 you set this parameter value to
AWS4HMACSHA256 This string identifies AWS Signature Version
4 (AWS4) and the HMACSHA256 algorithm (HMACSHA256)
XAmzCredential In addition to your access key ID this parameter also provides
scope (AWS region and service) for which the signature is valid
This value must match the scope you use in signature calculations
discussed in the following section The general form for this
parameter value is as follows
service>aws4_request
For example
AKIAIOSFODNN7EXAMPLE20130721useast1s3
aws4_request
For Amazon S3 the AWSservice string is s3 For a list of S3
AWSregion strings see Regions and Endpoints in the AWS
General Reference
XAmzDate
The date and time format must follow the ISO 8601 standard and
must be formatted with the yyyyMMddTHHmmssZ format For
example if the date and time was 08012016 153241982700
then it must first be converted to UTC (Coordinated Universal
Time) and then submitted as 20160801T083241Z
XAmzExpires Provides the time period in seconds for which the generated
presigned URL is valid For example 86400 (24 hours) This
value is an integer The minimum value you can set is 1 and the
maximum is 604800 (seven days)
A presigned URL can be valid for a maximum of seven days
because the signing key you use in signature calculation is valid
for up to seven days
XAmzSignedHeaders Lists the headers that you used to calculate the signature The
following headers are required in the signature calculations
API Version 20060301
39Amazon Simple Storage Service API Reference
Calculating a Signature
Query String Parameter
Name
Example Value
• The HTTP host header
• Any xamz* headers that you plan to add to the request
Note
For added security you should sign all the request
headers that you plan to include in your request
XAmzSignature Provides the signature to authenticate your request This
signature must match the signature Amazon S3 calculates
otherwise Amazon S3 denies the request For example
733255ef022bec3f2a8701cd61d4b371f3f28c9f193a1f02279211d48d5193d7
Signature calculations are described in the following section
Calculating a Signature
The following diagram illustrates the signature calculation process
The following table describes the functions that are shown in the diagram You need to implement code
for these functions
Function Description
Lowercase() Convert the string to lowercase
Hex() Lowercase base 16 encoding
API Version 20060301
40Amazon Simple Storage Service API Reference
Calculating a Signature
Function Description
SHA256Hash() Secure Hash Algorithm (SHA) cryptographic hash function
HMACSHA256() Computes HMAC by using the SHA256 algorithm with the signing
key provided This is the final signature
Trim() Remove any leading or trailing whitespace
UriEncode() URI encode every byte UriEncode() must enforce the following
rules
• URI encode every byte except the unreserved characters ＇A＇＇Z＇
＇a＇＇z＇ ＇0＇＇9＇ ＇＇ ＇＇ ＇_＇ and ＇~＇
• The space character is a reserved character and must be
encoded as 20 (and not as +)
• Each URI encoded byte is formed by a ＇＇ and the twodigit
hexadecimal value of the byte
• Letters in the hexadecimal value must be uppercase for
example 1A
• Encode the forward slash character ＇＇ everywhere except in
the object key name For example if the object key name is
photosJansamplejpg the forward slash in the key name
is not encoded
Caution
The standard UriEncode functions provided by your
development platform may not work because of
differences in implementation and related ambiguity in the
underlying RFCs We recommend that you write your own
custom UriEncode function to ensure that your encoding
will work
The following is an example uriencode() function in Java
public static String UriEncode(CharSequence input
boolean encodeSlash) {
StringBuilder result new
StringBuilder()
for (int i 0 i < inputlength() i++)
{
char ch inputcharAt(i)
if ((ch > ＇A＇ && ch < ＇Z＇) || (ch
> ＇a＇ && ch < ＇z＇) || (ch > ＇0＇ && ch < ＇9＇)
|| ch ＇_＇ || ch ＇＇ || ch ＇~＇ || ch
＇＇) {
resultappend(ch)
} else if (ch ＇＇) {
resultappend(encodeSlash
2F ch)
} else {
resultappend(toHexUTF8(ch))
}
}
return resulttoString()
}
API Version 20060301
41Amazon Simple Storage Service API Reference
An Example
For more information about the signing process (details of creating a canonical request string to sign
and signature calculations) see Signature Calculations for the Authorization Header Transferring
Payload in a Single Chunk (AWS Signature Version 4) (p 20) The process is generally the same
except that the creation of CanonicalRequest in a presigned URL differs as follows
• You don＇t include a payload hash in the Canonical Request because when you create a presigned
URL you don＇t know the payload content because the URL is used to upload an arbitrary payload
Instead you use a constant string UNSIGNEDPAYLOAD
• The Canonical Query String must include all the query parameters from the preceding table except
for XAmzSignature
• Canonical Headers must include the HTTP host header If you plan to include any of the xamz
* headers these headers must also be added for signature calculation You can optionally add all
other headers that you plan to include in your request For added security you should sign as many
headers as possible
An Example
Suppose you have an object testtxt in your examplebucket bucket You want to share this object
with others for a period of 24 hours (86400 seconds) by creating a presigned URL
httpss3amazonawscomexamplebuckettesttxt
XAmzAlgorithmAWS4HMACSHA256
&XAmzCredentialAKIAIOSFODNN7EXAMPLE2F201305242Fus
east12Fs32Faws4_request
&XAmzDate20130524T000000Z&XAmzExpires86400&XAmzSignedHeadershost
&XAmzSignature
The following steps illustrate first the signature calculations and then construction of the presigned
URL The example makes the following additional assumptions
• Request timestamp is Fri 24 May 2013 000000 GMT
• The bucket is in the US East (N Virginia) region and the credential Scope and the Signing
Key calculations use useast1 as the region specifier For more information see Regions and
Endpoints in the AWS General Reference
You can use this example as a test case to verify the signature that your code calculates however you
must use the same bucket name object key time stamp and the following example credentials
Parameter Value
AWSAccessKeyId AKIAIOSFODNN7EXAMPLE
AWSSecretAccessKey wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
1 StringToSign
a CanonicalRequest
GET
testtxt
XAmzAlgorithmAWS4HMACSHA256&XAmzCredentialAKIAIOSFODNN7EXAMPLE
2F201305242Fuseast12Fs32Faws4_request&XAmz
Date20130524T000000Z&XAmzExpires86400&XAmzSignedHeadershost
hostexamplebuckets3amazonawscom
API Version 20060301
42Amazon Simple Storage Service API Reference
Examples Signature Calculations
host
UNSIGNEDPAYLOAD
b StringToSign
AWS4HMACSHA256
20130524T000000Z
20130524useast1s3aws4_request
3bfa292879f6447bbcda7001decf97f4a54dc650c8942174ae0a9121cf58ad04
2 SigningKey
signing key HMACSHA256(HMACSHA256(HMACSHA256(HMACSHA256(AWS4 +
20130524)useast1)s3)aws4_request)
3 Signature
aeeed9bbccd4d02ee5c0109b86d86835f995330da4c265957d157751f604d404
Now you have all information to construct a presigned URL The resulting URL for this example is
shown as follows (you can use this to compare your presigned URL)
httpsexamplebuckets3amazonawscomtesttxtXAmz
AlgorithmAWS4HMACSHA256&XAmzCredentialAKIAIOSFODNN7EXAMPLE
2F201305242Fuseast12Fs32Faws4_request&XAmz
Date20130524T000000Z&XAmzExpires86400&XAmzSignedHeadershost&XAmz
Signatureaeeed9bbccd4d02ee5c0109b86d86835f995330da4c265957d157751f604d404
Examples Signature Calculations in AWS
Signature Version 4
Topics
• Signature Calculation Examples Using Java (AWS Signature Version 4) (p 44)
• Examples of Signature Calculations Using C# (AWS Signature Version 4) (p 45)
For authenticated requests unless you are using the AWS SDKs you have to write code to calculate
signatures that provide authentication information in your requests Signature calculation in AWS
Signature Version 4 (see Authenticating Requests (AWS Signature Version 4) (p 15)) can be a
complex undertaking and we recommend that you use the AWS SDKs whenever possible
This section provides examples of signature calculations written in Java and C# The code samples
send the following requests and use the HTTP Authorization header to provide authentication
information
• PUT object – Separate examples illustrate both uploading the full payload at once and uploading
the payload in chunks For information about using the Authorization header for authentication see
Authenticating Requests Using the Authorization Header (AWS Signature Version 4) (p 17)
• GET object – This example generates a presigned URL to get an object Query parameters provide
the signature and other authentication information Users can paste a presigned URL in their
browser to retrieve the object or you can use the URL to create a clickable link For information
API Version 20060301
43Amazon Simple Storage Service API Reference
Signature Calculation Examples Using Java
about using query parameters for authentication see Authenticating Requests Using Query
Parameters (AWS Signature Version 4) (p 38)
The rest of this section describes the examples in Java and C# The topics include instructions for
downloading the samples and for executing them
Signature Calculation Examples Using Java (AWS
Signature Version 4)
The Java sample that shows signature calculation can be downloaded at httpss3amazonawscom
awsjavasdksamplesAWSS3SigV4JavaSamplesjar In RunAllSamplesjava the main() function
executes sample requests to create an object retrieve an object and create a presigned URL for the
object The sample creates an object from the text string provided in the code
PutS3ObjectSampleputS3Object(bucketName regionName awsAccessKey
awsSecretKey)
GetS3ObjectSamplegetS3Object(bucketName regionName awsAccessKey
awsSecretKey)
PresignedUrlSamplegetPresignedUrlToS3Object(bucketName regionName
awsAccessKey awsSecretKey)
PutS3ObjectChunkedSampleputS3ObjectChunked(bucketName regionName
awsAccessKey awsSecretKey)
To test the examples on a Linuxbased computer
The following instructions are for the Linux operating system
1 At a command prompt change the directory to the directory that contains
AWSS3SigV4JavaSamplesjar
2 Extract the source files from AWSS3SigV4JavaSamplesjar
jar xvf AWSS3SigV4JavaSamplesjar
3 In a text editor open the file comamazonawsservicess3samples
RunAllSamplesjava Update code with the following information
• The name of a bucket where the new object can be created
Note
The examples use a virtualhosted style request to access the bucket To avoid potential
errors ensure that your bucket name conforms to the bucket naming rules as explained
in Bucket Restrictions and Limitations in the Amazon Simple Storage Service Developer
Guide
• AWS region where the bucket resides
If bucket is in the US East (N Virginia) region use useast1 to specify the region For a list of
other AWS regions go to Amazon Simple Storage Service (S3) in the AWS General Reference
4 Compile the source code and store the compiled classes into the bin directory
javac d bin source 6 verbose com
5 Change the directory to bin and then execute RunAllSamples
java comamazonawsservicess3sampleRunAllSamples
API Version 20060301
44Amazon Simple Storage Service API Reference
Signature Calculation Examples Using C#
The code runs all the methods in main() For each request the output will show the canonical
request the string to sign and the signature
Examples of Signature Calculations Using C# (AWS
Signature Version 4)
The C# sample that shows signature calculation can be downloaded at httpdocsawsamazoncom
AmazonS3latestAPIsamplesAmazonS3SigV4_Samples_CSharpzip In Programcs the main()
function executes sample requests to create an object retrieve an object and create a presigned URL
for the object The code for signature calculation is in the ＼Signers folder
PutS3ObjectSampleRun(awsRegion bucketName MySampleFiletxt)
ConsoleWriteLine(＼n＼n************************************************)
PutS3ObjectChunkedSampleRun(awsRegion bucketName
MySampleFileChunkedtxt)
ConsoleWriteLine(＼n＼n************************************************)
GetS3ObjectSampleRun(awsRegion bucketName MySampleFiletxt)
ConsoleWriteLine(＼n＼n************************************************)
PresignedUrlSampleRun(awsRegion bucketName MySampleFiletxt)
To test the examples with Microsoft Visual Studio 2010 or later
1 Extract the zip file
2 Start Visual Studio and then open the sln file
3 Update the Appconfig file with valid security credentials
4 Update the code as follows
• In Programcs provide the bucket name and the AWS region where the bucket resides The
sample creates an object in this bucket
5 Execute the code
6 To verify that the object was created copy the presigned URL that the program creates and then
paste it in a browser window
Authenticating Requests BrowserBased Uploads
Using POST (AWS Signature Version 4)
Amazon S3 supports HTTP POST requests so that users can upload content directly to Amazon
S3 Using HTTP POST to upload content simplifies uploads and reduces upload latency where
users upload data to store in Amazon S3 This section describes how you authenticate HTTP POST
requests For more information about HTTP POST requests how to create a form create a POST
policy and an example see Authenticating Requests in BrowserBased Uploads Using POST (AWS
Signature Version 4) (p 52)
To authenticate an HTTP POST request you do the following
1 The form must include the following fields to provide signature and relevant information that Amazon
S3 can use to recalculate the signature upon receiving the request
API Version 20060301
45Amazon Simple Storage Service API Reference
Authenticating HTTP POST Requests
Element Name Description
policy The Base64encoded security policy that describes what
is permitted in the request For signature calculation this
policy is the string you sign Amazon S3 must get this
policy so it can recalculate the signature
xamzalgorithm The signing algorithm used For AWS Signature Version
4 the value is AWS4HMACSHA256
xamzcredential In addition to your access key ID this provides scope
information you used in calculating the signing key for
signature calculation
It is a string of the following form
region>aws4_request
For example
AKIAIOSFODNN7EXAMPLE20130728useast1s3
aws4_request
For Amazon S3 the awsservice string is s3 For a list
of Amazon S3 awsregion strings see Regions and
Endpoints in the AWS General Reference
xamzdate It is the date value in ISO8601 format For example
20130728T000000Z
It is the same date you used in creating the signing key
This must also be the same value you provide in the
policy (xamzdate) that you signed
xamzsignature (AWS Signature Version 4) The HMACSHA256 hash of
the security policy
2 The POST policy must include the following elements
Element Name Description
xamzalgorithm The signing algorithm that you used to calculation the
signature For AWS Signature Version 4 the value is
AWS4HMACSHA256
xamzcredential In addition to your access key ID this provides scope
information you used in calculating the signing key for
signature calculation
It is a string of the following form
region>aws4_request
For example
AKIAIOSFODNN7EXAMPLE20130728useast1s3
aws4_request
xamzdate 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
API Version 20060301
46Amazon Simple Storage Service API Reference
Calculating a Signature
3 For signature calculation the POST policy is the string to sign
Calculating a Signature
The following diagram illustrates the signature calculation process
To Calculate a signature
1 Create a policy using UTF8 encoding
2 Convert the UTF8encoded policy to Base64 The result is the string to sign
3 Create the signature as an HMACSHA256 hash of the string to sign You will provide the signing
key as key to the hash function
4 Encode the signature by using hex encoding
For more information about creating HTML forms security policies and an example see the following
subtopics
• Creating an HTML Form (Using AWS Signature Version 4) (p 54)
• Creating a POST Policy (p 58)
• Examples BrowserBased Upload using HTTP POST (Using AWS Signature Version 4) (p 64)
• Additional Considerations for BrowserBased Uploads (p 66)
Amazon S3 Signature Version 4 Authentication
Specific Policy Keys
The following table shows the policy keys related Amazon S3 Signature Version 4 authentication that
can be in Amazon S3 policies In a bucket policy you can add these conditions to enforce specific
behavior when requests are authenticated by using Signature Version 4 For example policies see
Bucket Policy Examples Using Signature Version 4 Related Condition Keys (p 49)
Applicable Keys for s3* Actions or any of the Amazon S3 Actions
Applicable Keys Description
s3signatureversion Identifies the version of AWS Signature that you
want to support for authenticated requests For
authenticated requests Amazon S3 supports both
Signature Version 4 and Signature Version 2 You
API Version 20060301
47Amazon Simple Storage Service API Reference
Amazon S3 Signature Version 4
Authentication Specific Policy Keys
Applicable Keys Description
can add this condition in your bucket policy to
require a specific signature version
Valid values
AWS identifies Signature Version 2
AWS4HMACSHA256 identifies Signature
Version 4
s3authType Amazon S3 supports various methods of
authentication (see Authenticating Requests
(AWS Signature Version 4) (p 15) You can
optionally use this condition key to restrict
incoming requests to use a specific authentication
method For example you can allow only the
HTTP Authorization header to be used in
request authentication
Valid values
RESTHEADER
RESTQUERYSTRING
POST
s3signatureAge The length of time in milliseconds that a
signature is valid in an authenticated request
In Signature Version 4 the signing key is valid
for up to seven days (see Introduction to Signing
Requests (p 16) Therefore the signatures are
also valid for up to seven days You can use this
condition to further limit the signature age
Example value 100
API Version 20060301
48Amazon Simple Storage Service API Reference
Bucket Policy Examples Using Signature
Version 4 Related Condition Keys
Applicable Keys Description
s3xamzcontentsha256 You can use this condition key to disallow
unsigned content in your bucket
When you use Signature Version 4 for requests
that use the Authorization header you add the
xamzcontentsha256 header in the signature
calculation and then set its value to the hash
payload
You can use this condition key in your bucket
policy to deny any uploads where payloads are
not signed For example
• Deny uploads that use presigned URLs For
more information see Authenticating Requests
Using Query Parameters (AWS Signature
Version 4) (p 38)
• Deny uploads that use Authorization header
to authenticate requests but don＇t sign the
payload For more information see Signature
Calculations for the Authorization Header
Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p 20)
Valid value UNSIGNEDPAYLOAD
Bucket Policy Examples Using Signature Version 4
Related Condition Keys
Deny any Amazon S3 action on the examplebucket to anyone if request is authenticated using
Signature Version 4
{
Version 20121017
Statement [
{
Sid Test
Effect Deny
Principal *
Action s3*
Resource arnawss3examplebucket*
Condition {
StringEquals {
s3signatureversion AWS4HMACSHA256
}
}
}
]
}
API Version 20060301
49Amazon Simple Storage Service API Reference
Bucket Policy Examples Using Signature
Version 4 Related Condition Keys
The following bucket policy denies any Amazon S3 action on objects in examplebucket if the
signature is more than ten minutes old
{
Version 20121017
Statement [
{
Sid Deny request if signature is more than 10 min old
Effect Deny
Principal *
Action s3*
Resource arnawss3examplebucket3*
Condition {
NumericGreaterThan {
s3signatureAge 600000
}
}
}
]
}
The following bucket policy allows only requests that use the Authorization header for request
authentication Any POST or presigned URL requests will be denied
{
Version 20121017
Statement [
{
Sid Allow only requests that use Authorization header for
request authentication Deny POST or presigned URL requests
Effect Deny
Principal *
Action s3*
Resource arnawss3examplebucket3*
Condition {
StringNotEquals {
s3authType RESTHEADER
}
}
}
]
}
The following bucket policy denies any uploads that use presigned URLs
{
Version 20121017
Statement [
{
Sid Allow only requests that use Authorization header for
request authentication Deny POST or presigned URL requests
Effect Deny
Principal *
Action s3*
Resource arnawss3examplebucket3*
Condition {
StringNotEquals {
API Version 20060301
50Amazon Simple Storage Service API Reference
Bucket Policy Examples Using Signature
Version 4 Related Condition Keys
s3xamzcontentsha256 UNSIGNEDPAYLOAD
}
}
}
]
}
API Version 20060301
51Amazon Simple Storage Service API Reference
Authenticating Requests in Browser
Based Uploads Using POST (AWS
Signature Version 4)
Topics
• Calculating a Signature (p 53)
• Creating an HTML Form (Using AWS Signature Version 4) (p 54)
• Creating a POST Policy (p 58)
• Examples BrowserBased Upload using HTTP POST (Using AWS Signature Version 4) (p 64)
• Additional Considerations for BrowserBased Uploads (p 66)
Amazon S3 supports HTTP POST requests so that users can upload content directly to Amazon S3
By using POST end users can authenticate requests without having to pass data through a secure
intermediary node that protects your credentials Thus HTTP POST has the potential to reduce
latency
The following figure shows an Amazon S3 upload using a POST request
API Version 20060301
52Amazon Simple Storage Service API Reference
Calculating a Signature
Uploading Using POST
1 The user accesses your page from a web browser
2 Your web page contains an HTTP form that contains all the information necessary for the
user to upload content to Amazon S3
3 The user uploads content to Amazon S3 through the web browser
The process for sending browserbased POST requests is as follows
1 Create a security policy specifying conditions restricting what you want to allow in the request such
as bucket name where objects can be uploaded key name prefixes that you want to allow for the
object being created
2 Create signature that is based on the policy For authenticated requests the form must include a
valid signature and the policy
3 Create an HTML form that your users can access in order to upload objects to your Amazon S3
bucket
The following section describes how to create a signature to authenticate a request For information
about creating forms and security policies see Creating an HTML Form (Using AWS Signature Version
4) (p 54)
Calculating a Signature
For authenticated requests the HTML form must include fields for a security policy and a signature
• A security policy (see Creating a POST Policy (p 58)) controls what is allowed in the request
API Version 20060301
53Amazon Simple Storage Service API Reference
Creating HTML Forms
• The security policy is the StringToSign (see Introduction to Signing Requests (p 16)) in your
signature calculation
To Calculate a signature
1 Create a policy using UTF8 encoding
2 Convert the UTF8encoded policy bytes to Base64 The result is the StringToSign
3 Create a signing key
4 Use the signing key to sign the StringToSign using HMACSHA256 signing algorithm
For more information about creating HTML forms security policies and an example see the following
• Creating an HTML Form (Using AWS Signature Version 4) (p 54)
• Creating a POST Policy (p 58)
• Examples BrowserBased Upload using HTTP POST (Using AWS Signature Version 4) (p 64)
• Additional Considerations for BrowserBased Uploads (p 66)
Creating an HTML Form (Using AWS Signature
Version 4)
Topics
• HTML Form Declaration (p 55)
• HTML Form Fields (p 55)
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 highlevel information about the request The form fields contain detailed request information
This section describes how to create HTML forms For a working example of browserbased upload
using HTTP POST and related signature calculations for request authentication see Examples
BrowserBased Upload using HTTP POST (Using AWS Signature Version 4) (p 64)
The form and policy must be UTF8 encoded You can apply UTF8 encoding to the form by specifying
charsetUTF8 in the content attribute The following is an example of UTF8 encoding in the
HTML heading
API Version 20060301
54Amazon Simple Storage Service API Reference
HTML Form Declaration
Following is an example of UTF8 encoding in a request header
ContentType texthtml charsetUTF8
Note
The form data and boundaries (excluding the contents of the file) cannot exceed 20K
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 is examplebucket the URL is http
examplebuckets3amazonawscom
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 multipartformdata for both file uploads
and text area uploads For more information about enctype see RFC 1867
This is a form declaration for the bucket examplebucket