Signing requests
Many requests to Yandex Cloud Postbox are authenticated on the service side; therefore, they must be signed when sending. Yandex Cloud Postbox supports Amazon Signature Version 4Authorization
header.
Tip
To avoid signing requests, use authentication with an IAM token.
To get a signature:
- Create a canonical request.
- Generate a string to sign.
- Generate a signing key.
- Sign the string with the key.
- Optionally, debug the obtained data using the AWS CLI.
- Create the header.
Use HMAC
Create a canonical request
Use the following format:
<HTTPVerb>\n
<CanonicalURI>\n
<CanonicalQueryString>\n
<CanonicalHeaders>\n
<SignedHeaders>\n
UNSIGNED-PAYLOAD
Where:
-
HTTPVerb
: HTTP method -
CanonicalURI
: EndpointFor a list of endpoints and relevant HTTP methods, see the API reference. For example, the endpoint in the
GET /v2/email/configuration-sets HTTP/2
request is/v2/email/configuration-sets
. -
CanonicalQueryString
: Query parameters of the final URL. Provide all possible and supported parameters in the request. They must be URL-encoded and sorted alphabetically.Here is an example:
NextToken=my%2Ftoken&PageSize=10
. -
CanonicalHeaders
: List of request headers and their values.The list must follow these requirements:
- Each header must be separated with the line break symbol
\n
. - Header names must be lowercase.
- Headers must be sorted alphabetically.
- There may not be any extra spaces.
- The list must contain the
host
header and allx-amz-*
headers used in the request.
You can also add any request header to the list. The more headers you sign, the safer your request is going to be.
Examples:
host:postbox.cloud.yandex.net x-amz-date:20240920T091646Z
- Each header must be separated with the line break symbol
-
SignedHeaders
: List of header names used for request signature generation. Provide the headers in lowercase, sort them alphabetically, and separate with semicolons.Example:
content-type;host;x-amz-date
.
Add the UNSIGNED-PAYLOAD
string at the end of your canonical request.
Generate a string to sign
A string to sign is a concatenation of the following strings:
"AWS4-HMAC-SHA256" + "\n" +
"<time_in_ISO_8601_format>" + "\n" +
"<date_in_YYYYMMDD_format>/ru-central1/ses/aws4_request" + "\n" +
Hex(SHA256Hash(<canonical_request>))
Here is an example of time in ISO 860120240920T091646Z
.
Generate a signing key
Before you start, generate a static access key.
To generate a signing key:
-
Use the secret key to encode the date:
DateKey = sign("AWS4" + "SecretKey", "yyyymmdd")
-
Encode the region using the
DateKey
you got in the previous step:RegionKey = sign(DateKey, "ru-central1")
-
Encode the service using the
RegionKey
you got in the previous step:ServiceKey = sign(RegionKey, "s3")
-
Get the signing key:
SigningKey = sign(ServiceKey, "aws4_request")
Sign the string with the key
Sign the string and convert it to hexadecimal format:
signature = Hex(sign(SigningKey, StringToSign))
Optionally, debug the obtained data using the AWS CLI
To debug the process of signing requests, use the AWS CLI utility with the --debug
parameter. It adds CanonicalRequest
, StringToSign
, and Signature
to the command output. You can compare these against your values.
In the terminal, run the configuration create command and see how request parameters are generated:
aws sesv2 create-configuration-set \
--endpoint-url=https://postbox.cloud.yandex.net \
--profile default \
--configuration-set-name <configuration_name> \
--debug
Note
For this example, the service account you are using to run the aws
commands needs the postbox.editor
role or higher.
Result:
...
2024-09-02 13:16:46,063 - MainThread - botocore.auth - DEBUG - CanonicalRequest:
POST
/v2/email/configuration-sets
content-type:application/json
host:postbox.cloud.yandex.net
x-amz-date:20240920T091646Z
content-type;host;x-amz-date
e9cc542601e782471dc41e9c1aa0a6c9e55cf6b926c0e2b200e461d0********
2024-09-02 13:16:46,063 - MainThread - botocore.auth - DEBUG - StringToSign:
AWS4-HMAC-SHA256
20240920T091646Z
20240902/ru-central1/ses/aws4_request
bcbaab5d2a5f44555276ec63a07e4141a04d72b886b419fe280ca07d********
2024-09-02 13:16:46,063 - MainThread - botocore.auth - DEBUG - Signature:
d88f587982912662d886c77de0c110aad8fa2899bc2e733ff4f03f7e********
...
Authorization
header
Create the Create the Authorization
header in the following format:
Authorization: AWS4-HMAC-SHA256 Credential=<static_key_ID>/<date>/ru-central1/ses/aws4_request SignedHeaders=<signed_headers> Signature=<signature>
Use this header when accessing the API directly, without the AWS CLI or apps.
In the header, specify the following:
- Static access key ID you obtained when getting started.
- Date in
YYYYMMDD
format. - Signed headers, e.g.,
content-type;host;x-amz-date
. Learn more about signed headers here. - Request signature.