-
Notifications
You must be signed in to change notification settings - Fork 16
/
aws_api.aws.txt
218 lines (177 loc) · 11.8 KB
/
aws_api.aws.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
AWS API
VERSION ==> #2023-04-04
SEE ALSO ==> #Main AWS doc
SUMMARY ==> #Request: action, version, query|JSON|XML
#Response: errors, requestId
#Authorization: signature version 4a|4b|2
/=+===============================+=\
/ : : \
)==: REQUEST :==(
\ :_______________________________: /
\=+===============================+=/
PROTOCOL ==> #HTTPS
#HTTP allowed for some SERVICEs
ACTION + VERSION ==> #Depending on SERVICE:
# - REQ.Action 'ACTION', REQ.Version 'SVERSION'
# - REQ.Operation 'ACTION'
# - X-Amz-Target [C]: SERVICE[_VERSION].SDK_ACTION (CamelCase)
# - X-Amz-SERVICE-Version: VERSION [C]
RPC ==> #Depending on SERVICE:
# - RPC: POST|GET /
# - REST: POST|PUT|GET|DELETE [/VERSION]/RESOURCE
REQ #Request parameters
#Depending on SERVICE:
# - query variables VARR
# - ARR: VAR.NUM or VAR.members.NUM (1-based)
# - JSON
# - XML
# - ARR: <KEYSet|KEYList><VAR></VAR>...</KEYSet|KEYList>
HEADERS ==> #Sometimes used for REQ|RES
#Either standard, or X-Amz[n]-*
Content-Type [C|S] #
Content-Length [C|S] #
REQ.ClientToken #STR. Do not perform if already performed with same STR.
#Meant for idempotence.
#Only for some SERVICEs (EC2, VPC, some of S3)
#Sometimes called ClientRequestToken
PAGINATION ==> #SERVICE-specific
/=+===============================+=\
/ : : \
)==: RESPONSE :==(
\ :_______________________________: /
\=+===============================+=/
Connection [S] #
Date [S] #
RES #Response body
#Either JSON or XML, depending on SERVICE
RES.Errors #OBJ_ARR:
# - Code 'CODE'
# - can see in online doc for each ACTION
# - Message STR
# (sometimes)
# - Resource STR
# - RequestId STR
ERROR_RES #Alternative to RES.Errors for some SERVICEs
#OBJ:
# - code 'CODE'
# - message STR
# - type 'Client|Server|Unknown'
#Uses HTTP status code too
REQ_ID #'UUID'. Depending on SERVICE:
# - RES.requestId
# - RES.ResponseMetadata.RequestId
# - x-amz[n]-request[-]id [S]
# - sometimes secondary ID: x-amz-id-2 [S] (machine host)
EVENTUAL CONSISTENCY ==> #Many endpoints use eventual consistency:
# - action happens async, after response
# - effects takes time to propagate, i.e. different clients might return different results
#Those often offer WAIT methods (see AWS JavaScript doc)
/=+===============================+=\
/ : : \
)==: AUTHORIZATION :==(
\ :_______________________________: /
\=+===============================+=/
AUTHORIZATION ==> #Only when using ACCESS_KEY (not LOGIN_PROFILE, or other credentials)
#Signed checksum include: ACTION, full request, date, REGION
VERSION 4 SIGNATURE ==> #
REQ.X-Amz-Algorithm #'AWS4-HMAC-SHA256'
REQ.X-Amz-Credential #'ACCESS_KEY_ID/YYYYMMDD/REGION/SERVICE/aws4_request'
REQ.X-Amz-SignedHeaders #'HEADER;...' to include in signature
REQ.X-Amz-Signature #'HMAC_SHA256':
# - of:
# - 'AWS4-HMAC-SHA256'
# - 'DATE'
# - 'YYYYMMDD/REGION/SERVICE/aws4_request'
# - 'SHA256' of:
# - HTTP method
# - URI path
# - query string
# - "canonical headers"
# - must include Host|:authority [C], [X-]Amz-* [C], Date [C], Content-Type [C], Content-Length [C], Range [C]
# - can|should include others
# - sorted
# - names + values
# - "signed headers": like canonical headers, but only keys
# - 'SHA256' of request body
# - signed with 'HMAC_SHA256'
# - of:
# - 'YYYYMMDD'
# - 'REGION'
# - 'SERVICE'
# - 'aws4_request'
# - signed with 'AWS4' + SECRET_ACCESS_KEY
REQ.X-Amz-SecurityToken #STS 'SESSION_TOKEN'
REQ.X-Amz-Date #'DATE'
REQ.X-Amz-Expires #NUM (in secs) to expires signature
#Only with some SERVICEs like S3
ALTERNATIVE ==> #
Authorization:
AWS4-HMAC-SHA256
AUTH_VAR=VAL,... [C] #
AUTH_VAR Credential
AUTH_VAR SignedHeaders
AUTH_VAR Signature
X-Amz-SecurityToken [C]
X-Amz-Date [C] #Same as above
VERSION 4A SIGNATURE ==> #Another alternative which supports specifying more than one REGION
#Required for S3 MACCESSPOINTs
#Uses algo AWS4-ECDSA-P256-SHA256
#It seems like they cannot use x-amz-content-sha256 [C]
#Requires installing @aws-sdk/signature-v4-crt (which has native dependencies)
VERSION 2 SIGNATURE ==> #Only for SimpleDB
REQ.AWSAccessKeyId #ACCESS_KEY_ID
REQ.SignatureVersion #2
REQ.SignatureMethod #'HmacSHA256'
REQ.Signature #'HMAC_SHA256':
# - of:
# - HTTP method
# - 'SERVICE_DOMAIN'
# - URI path
# - all request parameters, sorted
# - including AWSAccessKkeyId, Action, SignatureMethod, SignatureVersion, Timestamp
# - signed with SECRET_ACCESS_KEY
REQ.SecurityToken #STS 'SESSION_TOKEN'
REQ.Timestamp #'DATE'
REQ.Expires #'DATE'. Cannot be used together with REQ.Timestamp
/=+===============================+=\
/ : : \
)==: ADVANCED SIGNATURE :==(
\ :_______________________________: /
\=+===============================+=/
x-amz-content-sha256: STR [C] #Changes the value used for the "request body" part of the signature to allow for:
# - unsigned request body
# - chunked request body
#Only with some services (S3)
x-amz-content-sha256:
SHA256_HASH [C] #Default behavior
x-amz-content-sha256: #Request body in signature is constant: UNSIGNED_PAYLOAD, i.e. not part of signature
UNSIGNED_PAYLOAD [C] #Can still use x-amz-signedheaders [C] (e.g. x-amz-checksum-* [C] with S3) to validate request body
x-amz-content-sha256:
STREAMING-UNSIGNED-PAYLOAD
-TRAILER [C] #Same but using multiple chunks
x-amz-content-sha256: #When sending the request body in multiple chunks (but in a single request):
STREAMING-AWS4-HMAC-SHA256 # - for example with Transfer-Encoding [C]
-PAYLOAD [C] # - but can be any other way
#Each chunk is prepended by: NUM;chunk-signature=SIGNATURE
# - NUM: chunk size, in hex
# - SIGNATURE: signature using as request body concatenation of:
# - previous SIGNATURE
# - initial one is constant: STREAMING-*
# - SHA256 of an empty string
# - SHA256 of chunk data
#Final chunk must have empty data
x-amz-decoded-content-length:
NUM [C] #Like Content-Length [C], but without chunk prefix lines
Content-Encoding:
aws-chunked[,STR...] [C] #Must be used instead of Content-Encoding: STR [C]
x-amz-content-sha256:
STREAMING-AWS4-ECDSA-P256
-SHA256-PAYLOAD [C] #Same as STREAMING-AWS4-HMAC-SHA256-PAYLOAD, but using signature 4a instead of 4
x-amz-content-sha256: #Like STREAMING-* except send some request headers after last chunk
STREAMING-*-TRAILER [C] #Send an additional final chunk with concatenation of:
# - HEADER:VAL (one per line)
# - x-amz-trailer-signature:SIGNATURE
# - SIGNATURE is same as above, but using 'HEADER:VAL' lines as data
x-amz-trailer: HEADER,... [C] #List of trailer headers