Начало работы c API Object Storage

Чтобы получить доступ к Object Storage API сгенерируйте API-ключ. Для работы с Object Storage API можно использовать техническую учетную запись — сервисный аккаунт или личную учетную запись с персональным API-ключом.

Endpoint для методов API — s3.cloud.ru.

Генерация API-ключа

Чтобы получить ключи доступа к Object Storage API:

  1. Авторизуйтесь в личном кабинете.

  2. Выполните одно из следующих действий:

  3. Сохраните key ID и key Secret (пароль).

Генерирование подписи

Многие API-запросы к Object Storage аутентифицируются на стороне сервиса. При отправке запроса пользователю необходимо его подписать.

В разделе описаны процессы генерации подписи AWS Signature V4 и добавления подписи к API-запросу.

Чтобы получить подпись для API-запроса:

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

  2. Создайте канонический запрос.

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

  4. Подпишите строку ключом.

Генерирование подписывающего ключа

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

DateKey = HMAC-SHA256("AWS4"+"<KeySecret>", "<YYYYMMDD>")
DateRegionKey = HMAC-SHA256(DateKey, "ru-central-1")
DateRegionServiceKey = HMAC-SHA256(DateRegionKey, "s3")
SigningKey = HMAC-SHA256(DateRegionServiceKey, "aws4_request")

Параметры для первого вызова хеш-функции:

Параметр

Описание

<KeySecret>

Key Secret, сгенерированный на шаге Генерация API-ключа.

<YYYYMMDD>

Текущая дата.

Создание канонического запроса

Для вычисления подписи понадобится строка, которая генерируется с помощью канонического запроса. Создайте канонический запрос CanonicalRequest в формате:

CanonicalRequest = \`
<HTTPMethod>\n
<CanonicalURI>\n
<CanonicalQueryString>\n
<CanonicalHeaders>\n
<SignedHeaders>\n
<HashedPayload>
\`

Описание параметров:

Параметр

Описание

<HTTPMethod>

HTTP-метод запроса: GET, PUT, HEAD или DELETE.

<CanonicalURI>

Путь к ресурсу, к которому относится URI-запрос. Путь начинается с косой черты /, следующей после доменного имени, и продолжается до конца строки или до вопросительного знака ?.

Например, для URL-запроса https://s3.cloud.ru/my-bucket/my-file.txt, путь к ресурсу — /my-bucket/my-file.txt.

<CanonicalQueryString>

Параметры строки запроса — все, что следует за вопросительным знаком ? в пути к ресурсу. Отсортируйте параметры в алфавитном порядке по имени ключа и разделите амперсандом &.

Если в запросе нет параметров, оставьте строку пустой \n.

Например, для URL-запроса https://s3.cloud.ru/my-bucket?tag=my-tag&project=my-project, список параметров — project=my-project&tag=my-tag.

<CanonicalHeaders>

Заголовки и их значения, разделенные символом новой строки \n. Отсортируйте заголовки в алфавитном порядке и укажите их в нижнем регистре, без пробелов. Заголовок и значение разделяются двоеточием :.

Например:

host:s3.cloud.ru
x-amz-content-sha256:e3b0c...
x-amz-date:20230101T220855Z

<SignedHeaders>

Имена заголовков без значений, отсортированные в алфавитном порядке, в нижнем регистре и через точку с запятой ;.

Например:

host;x-amz-content-sha256;x-amz-date

<HashedPayload>

Хэш SHA256 тела запроса Hex(SHA256Hash()). Если тела запроса нет, рассчитайте хэш от пустой строки Hex(SHA256Hash("")).

Пример канонического запроса:

GET
/s3.cloud.ru/my-bucket/my-file.txt


host:s3.cloud.ru
x-amz-content-sha256:e3b0c...
x-amz-date:20230101T220855Z


host;x-amz-content-sha256;x-amz-date
e3b0c...

Генерирование строки для подписи

Получите строку для подписи StringToSign:

StringToSign = "AWS4-HMAC-SHA256" + "\n" +
<timeStampISO8601Format> + "\n" +
<Scope> + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

Описание параметров:

Параметр

Описание

AWS4-HMAC-SHA256

Алгоритм шифрования.

<timeStampISO8601Format>

Текущее время UTC в формате ISO 8601.

Например, 20230101T220855Z.

<Scope>

Строка в формате <YYYYMMDD>/ru-central-1/s3/aws4_request", где <YYYYMMDD> — текущая дата.

<CanonicalRequest>

Канонический запрос.

Подпись строки

Подпись вычисляется как хэш HMAC-SHA256 строки для подписи и подписывающего ключа.

Signature = HMAC-SHA256(SigningKey, StringToSign)

Добавление подписи к запросу

Если запрос требует аутентификации, подпишите его в HTTP-заголовке Authorization или параметрах query.

Аутентификация через HTTP-заголовок Authorization

Использование заголовка Authorization является одним из вариантов аутентификации.

Authorization: AWS4-HMAC-SHA256
Credential=<TENANT_ID>:<KEY_ID>/<YYYYMMDD>/ru-central-1/s3/aws4_request,
SignedHeaders=host;range;x-amz-date,
Signature=73325...

Описание параметров:

Параметр

Описание

Authorization

Версия подписи (AWS4) и алгоритм, который использовался для генерации подписи (HMAC-SHA256).

Credential

Информация о запросе в формате:

<TENANT_ID>:<KEY_ID>/<YYYYMMDD>/ru-central-1/s3/aws4_request, где:

  • TENANT_ID — идентификатор тенанта;

  • KEY_ID — Key ID, сгенерированный на шаге Генерация API-ключа;

  • <YYYYMMDD> – текущая дата.

SignedHeaders

Список имен заголовков, которые использовались при вычислении подписи. В нижнем регистре, через точку с запятой.

Signature

Вычисленная подпись.

Аутентификация через параметры query

Используйте аутентификацию через query-параметры, если нужно указать все параметры запроса в URL. Этот метод так же обозначается как подписанный URL (Presigned URL).

https://s3.cloud.ru/my-bucket/my-file.txt
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=<TENANT_ID>:<KEY_ID>/<YYYYMMDD>/ru-central-1/s3/aws4_request
&X-Amz-Date=20230101T220855Z
&X-Amz-Expires=86400
&X-Amz-SignedHeaders=host
&X-Amz-Signature=73325...

Описание параметров:

Параметр

Описание

X-Amz-Algorithm

Версия подписи (AWS4) и алгоритм, который использовался для генерации подписи (HMAC-SHA256).

X-Amz-Credential

Информация о запросе в формате

<TENANT_ID>:<KEY_ID>/<YYYYMMDD>/ru-central-1/s3/aws4_request, где

  • TENANT_ID — идентификатор тенанта;

  • KEY_ID — Key ID сервисного аккаунта, сгенерированный на шаге Генерация API-ключа;

  • <YYYYMMDD> – текущая дата.

X-Amz-Date

Время UTC в формате ISO 8601.

Например, 20230101T220855Z.

X-Amz-Expires

Время в секундах, в течение которого сгенерированный подписанный URL будет действителен.

Например, 86400 секунд (1 день). Допустимые значения: целые числа от 1 до 604800 (7 дней).

X-Amz-SignedHeaders

Список имен заголовков, которые использовались при вычислении подписи. Следующие заголовки обязательны:

  • Host;

  • любой X-Amz-*, который планируется добавить в запрос.

Для дополнительной безопасности рекомендуется подписывать все заголовки.

X-Amz-Signature

Вычисленная подпись.
Была ли статья полезной ?
Предыдущая статья
Справочник API
Следующая статья
Методы
/ DOCS
Evolution