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 4 for signing. It is used in the Authorization header.

To get a signature:

1. Create a canonical request
2. Generate a string to sign
3. Generate a signing key
4. Sign the string with the key
5. Optionally, debug the obtained data using the AWS CLI
6. Create the Authorization header

Use HMAC with the SHA256 hash function for signing. This technique supports many programming languages. The examples below assume the code uses functions for encoding and hashing strings with the appropriate technique.

Create a canonical requestCreate a canonical request

Use the following format:

<HTTPVerb>\n
<CanonicalURI>\n
<CanonicalQueryString>\n
<CanonicalHeaders>\n
<SignedHeaders>\n
UNSIGNED-PAYLOAD

Where:

• HTTPVerb: HTTP method

• CanonicalURI: Endpoint

  For 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.

  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 all x-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.

  Example:

  host:postbox.cloud.yandex.net
  x-amz-date:20240920T091646Z
  

• 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 signGenerate 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 8601 format: 20240920T091646Z.

Generate a signing keyGenerate a signing key

Before you start, generate a static access key.

To generate a signing key:

1. Use the secret key to encode the date:

   DateKey = sign("AWS4" + "SecretKey", "yyyymmdd")
   

2. Encode the region using DateKey you got in the previous step:

   RegionKey = sign(DateKey, "ru-central1")
   

3. Encode the service using RegionKey you got in the previous step:

   ServiceKey = sign(RegionKey, "s3")
   

4. Get the signing key:

   SigningKey = sign(ServiceKey, "aws4_request")
   

Sign the string with the keySign 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 CLIOptionally, 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.

aws sesv2 create-configuration-set \
   --endpoint-url=https://postbox.cloud.yandex.net \
   --profile default \
   --configuration-set-name <configuration_name> \
   --debug

...
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********
...

Create the Authorization headerCreate the Authorization header

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.