tocdepth: 2

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

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

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

Генерация API-ключа
Генерирование подписи
Добавление подписи к запросу
- Аутентификация через HTTP-заголовок Authorization
- Аутентификация через параметры query

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

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

Авторизуйтесь в личном кабинете.
Выполните одно из следующих действий:
- Создайте сервисный аккаунт и сгенерируйте и ключи доступа.
- Создайте персональный API-ключ.
Сохраните key ID и key Secret (пароль).

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

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

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

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

Сгенерируйте подписывающий ключ.
Создайте канонический запрос.
Сгенерируйте строку для подписи.
Подпишите строку ключом.

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

Чтобы получить подписывающий ключ 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`	Вычисленная подпись.

Была ли статья полезной?

Спасибо за отзыв! Что можно улучшить?

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