Подписывание запросов

Многие запросы к Yandex Cloud Postbox аутентифицируются на стороне сервиса, поэтому запросы нужно подписывать при отправке. Yandex Cloud Postbox поддерживает подпись Amazon Signature Version 4. Она используется в заголовке Authorization.

Чтобы получить подпись:

1. Составьте канонический запрос.
2. Сгенерируйте строку для подписи.
3. Сгенерируйте подписывающий ключ.
4. Подпишите строку с помощью ключа.
5. (Опционально) Отладьте полученные данные с помощью AWS CLI.
6. Составьте заголовок Authorization.

Для подписи используйте механизм HMAC с хеширующей функцией SHA256. Этот механизм поддерживают многие языки программирования. В примерах ниже предполагается, что в коде используются функции для кодирования и хеширования строк с нужным механизмом.

Составьте канонический запросСоставьте канонический запрос

Сформируйте канонический запрос по следующему формату:

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

Где:

• HTTPVerb — HTTP-метод.

• CanonicalURI — эндпоинт.

  Список эндпоинтов и нужных для них HTTP-методов приведен в Справочнике API. Например, в запросе GET /v2/email/configuration-sets HTTP/2 эндпоинт — это /v2/email/configuration-sets.

• CanonicalQueryString — query-параметры конечного URL. Укажите все возможные и поддержанные в запросе параметры. Они должны быть URL-кодированы и отсортированы по алфавиту.

  Пример: NextToken=my%2Ftoken&PageSize=10.

• CanonicalHeaders — список заголовков запроса со значениями.

  Требования:

  • Каждый заголовок отделяется символом новой строки \n.
  • Имена заголовков должны быть в нижнем регистре.
  • Заголовки должны быть отсортированы по алфавиту.
  • Не должно быть лишних пробелов.
  • Список должен содержать заголовок host и все заголовки x-amz-*, которые используются в запросе.

  Дополнительно в список можно добавить любой из заголовков запроса. Чем больше вы подпишете заголовков, тем безопаснее будет запрос.

  Пример:

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

• SignedHeaders — список названий заголовков, которые используются для составления подписи запроса. Укажите заголовки в нижнем регистре, отсортируйте их по алфавиту и разделите точками с запятыми.

  Пример: content-type;host;x-amz-date.

В конце канонического запроса добавьте строку UNSIGNED-PAYLOAD.

Сгенерируйте строку для подписиСгенерируйте строку для подписи

Строка для подписи — это конкатенация следующих строк:

"AWS4-HMAC-SHA256" + "\n" +
"<время_в_формате_ISO_8601>" + "\n" +
"<дата_в_формате_YYYYMMDD>/ru-central1/ses/aws4_request" + "\n" +
Hex(SHA256Hash(<канонический_запрос>))

Пример времени в формате ISO 8601: 20240920T091646Z.

Сгенерируйте подписывающий ключСгенерируйте подписывающий ключ

Перед началом работы подготовьте статический ключ доступа.

Чтобы сгенерировать подписывающий ключ:

1. Закодируйте дату с помощью секретного ключа:

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

2. Закодируйте регион с помощью полученного на предыдущем шаге ключа DateKey:

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

3. Закодируйте сервис с помощью полученного на предыдущем шаге ключа RegionKey:

   ServiceKey = sign(RegionKey, "s3")
   

4. Получите подписывающий ключ:

   SigningKey = sign(ServiceKey, "aws4_request")
   

Подпишите строку с помощью ключаПодпишите строку с помощью ключа

Подпишите строку и преобразуйте ее в шестнадцатеричное представление:

signature = Hex(sign(SigningKey, StringToSign))

(Опционально) Отладьте полученные данные с помощью AWS CLI(Опционально) Отладьте полученные данные с помощью AWS CLI

Чтобы отладить подписывание запросов, используйте утилиту AWS CLI с параметром --debug. Он добавляет в вывод команды канонический запрос CanonicalRequest, строку для подписи StringToSign и подпись запроса Signature. Вы можете сравнить их с вашими значениями.

aws sesv2 create-configuration-set \
   --endpoint-url=https://postbox.cloud.yandex.net \
   --profile default \
   --configuration-set-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********
...

Составьте заголовок AuthorizationСоставьте заголовок Authorization

Сформируйте заголовок Authorization по следующему формату:

Authorization: AWS4-HMAC-SHA256 Credential=<идентификатор_статического_ключа>/<дата>/ru-central1/ses/aws4_request SignedHeaders=<подписанные_заголовки> Signature=<подпись>

Используйте такой заголовок, если обращаетесь к API напрямую, без AWS CLI и приложений.

В заголовке укажите:

• Идентификатор статического ключа доступа, полученный во время подготовки к работе.
• Дату в формате YYYYMMDD.
• Подписанные заголовки, например content-type;host;x-amz-date. Подробнее о подписанных заголовках.
• Подпись для запроса.