← Блог
10 мин чтения
|
Опубликовано
|
Обновлено

Ротация API-ключей: создать, задать, проверить, завершить

Как ротировать API-ключи без простоя: шаблон «создать, установить, проверить, завершить», интервалы по NIST, менеджеры секретов и особенности Chaingateway.

Главы
C
Chaingateway Team
Эксперты по блокчейну

Проверил(а) Maurice Sobiera

Изометрическая иллюстрация ротации API-учётных данных

Ротация API-ключа — это замена действующего ключа новым по расписанию или после утечки с последующим отключением старого. Надёжный шаблон состоит из четырёх шагов: создать, установить, проверить, завершить. Короткое перекрытие позволяет работать обоим ключам, поэтому запросы в пути не падают. NIST и OWASP советуют автоматизировать эту процедуру.

Зачем ротировать API-ключи?

Ротация сокращает время, в течение которого утёкший ключ полезен злоумышленнику. Каждый API-ключ — постоянный риск. Ключ может утечь через закоммиченный файл .env, скомпрометированный раннер CI или ноутбук бывшего сотрудника. Чем дольше ключ остаётся действительным, тем дольше утечка остаётся пригодной для эксплуатации.

OWASP относит этот риск к NHI7, долгоживущим секретам, в своём Top 10 для не-человеческих идентичностей. Там описаны API-ключи и токены с датами истечения в далёком будущем или без них вовсе. Такие секреты названы крайне распространёнными, потому что ротировать их трудно, а короткоживущие альтернативы доступны не всегда.

Ротация важнее всего для этих учётных данных:

  • Ключи с широкими правами, например administrator, billing или запись в производственные данные.
  • Учётные данные, которыми пользуются несколько сервисов или команд.
  • Всё, что встроено в клиентский код, мобильные приложения или сторонние интеграции.
  • Токены, которые хотя бы ненадолго попадали в публичный репозиторий.

Где возможно, замените статический ключ короткоживущим токеном OAuth или системы идентификации рабочих нагрузок. Учётные данные, которые истекают сами, не требуют задачи ротации.

Как часто ротировать API-ключи?

NIST называет одно конкретное число, и оно относится к ключам подписи. В NIST IR 8587 сказано, что для систем с высоким уровнем воздействия ключи подписи должны использоваться не дольше 90 дней. Для систем со средним и низким уровнем воздействия более длительный срок может быть уместен, но он должен быть меньше одного года. В отчёте также говорится, что нужно документировать криптопериоды и применять автоматическую ротацию.

NIST не задаёт интервалов для обычных API-ключей. Значения ниже — наши рекомендации, выведенные из подхода к риску, описанного в отчёте. Это не требование NIST.

Учётные данныеРекомендуемый максимальный возрастПричина
Ключи подписи систем с высоким воздействием90 дней (NIST)Наибольший радиус ущерба
API-ключи для связи сервис-сервисот 30 до 90 днейЗависит от прав
Токены CI/CD30 днейЧасто дают доступ к деплою
API-ключи для пользователей90 дней и сразу после подозрения на утечкуСуществует много копий

Столбчатая диаграмма рекомендуемых криптопериодов: ключи подписи до 90 дней, ключи сервис-сервис от 30 до 90 дней, токены CI/CD до 30 дней, API-ключи для пользователей 90 дней

Правило за таблицей простое: чем больший ущерб может нанести утёкшее учётное данное, тем короче должен быть срок его использования. Ручной цикл в 30 дней реалистичен для нескольких ключей. Для десятков сервисов нужна автоматизация. NIST делает тот же вывод. Более короткие криптопериоды заставляют организации автоматизировать ротацию и регулярно отрабатывать переключение.

Где хранить API-ключи?

Храните ключи в менеджере секретов, который ведёт версии секретов, запускает хуки ротации, ограничивает доступ и журналирует каждое чтение. Таблицы и общие файлы .env ничего из этого не умеют. Перед выбором проверьте четыре возможности:

  • Версионирование, чтобы текущий и предыдущий секрет могли существовать одновременно.
  • Хуки ротации, которые запускают функцию ротации по расписанию или по событию.
  • Ограничение доступа, чтобы агент ротации не мог прочитать все секреты.
  • Журналы аудита, которые фиксируют, кто и какой секрет читал или ротировал.

AWS Secrets Manager поддерживает плановую ротацию через функцию ротации. HashiCorp Vault умеет выдавать динамические секреты, которые истекают сами. Облачные сервисы управления ключами, привязанные к ролям IAM, выполняют ту же функцию.

Если архитектура позволяет, откажитесь от статических ключей. OWASP рекомендует динамические секреты там, где это возможно, поскольку они уменьшают поверхность для повторного использования учётных данных. Временные учётные данные AWS STS или управляемые идентичности Azure и Google Cloud истекают через минуты или часы, поэтому долгоживущего секрета, который нужно ротировать, не остаётся.

Что означают шаги «создать, установить, проверить, завершить»?

Четыре шага — это шаблон, который шпаргалка OWASP описывает для функций ротации в бессерверной среде. Он применим к любому менеджеру секретов или собственному скрипту.

  1. Создать: сгенерировать новую версию секрета, не трогая используемую.
  2. Установить: передать новое учётное данное зависимому сервису или хранилищу конфигурации.
  3. Проверить: запустить интеграционную проверку, которая доказывает, что новый секрет проходит аутентификацию.
  4. Завершить: сделать новый секрет действующим, а старый отозвать или запланировать его удаление.

Шаг, который команды пропускают, — перекрытие между «установить» и «завершить». NIST описывает его как перекрывающееся принятие старого и нового ключей. Ротация должна планировать переход на новый ключ заранее, до истечения срока, чтобы получатели какое-то время принимали обе версии. Правильная длина перекрытия зависит от вашей системы. Оно должно быть длиннее самого долгого запроса в пути и длиннее времени, за которое ваши клиенты подхватят новое значение, включая время жизни кешей. Выберите число, затем проверьте его на staging.

ТриггерЛучше всего подходитМодель прав
По расписаниюПредсказуемый ритм, например 30 или 90 днейРоль ротации, ограниченная одним путём секрета
По событиюОбнаружена компрометация, увольнение сотрудникаПовышенные права, ограниченные по времени, отзываются после выполнения
ВручнуюРазовые аудиты, подключение нового сервисаОдобрение человеком плюс MFA

У агента ротации должен быть как можно более узкий набор прав: запись в один секрет и ничего шире.

Что должен включать чек-лист ротации?

Пройдите четыре пункта, прежде чем что-либо автоматизировать.

  1. Сделайте резервную копию текущего секрета и проверьте откат, чтобы он не остался теорией.
  2. Постройте интеграционный тест, который проверяет новое учётное данное на реальном endpoint.
  3. Создайте роль ротации, ограниченную ровно одним секретом.
  4. Записывайте каждое событие ротации в журнал аудита.

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

В журнале фиксируйте, кто или что запустило каждую ротацию, замаскированную версию старого и нового ключа, режим (плановый, ручной или аварийный) и результат. Следите за резким всплеском запросов от одного ключа, за вызовами с IP-адресов или из регионов, которые ключ никогда раньше не использовал, и за запросами с ключом, который уже должен был истечь. Проводите сканирование репозиториев на жёстко заданные ключи и ведите инвентарь, потому что ключ вне инвентаря никогда не будет ротирован.

Как ротировать учётные данные Chaingateway?

Интеграция с Chaingateway использует три вида секретов, и каждый ротируется по-своему.

API-токен аутентифицирует ваши запросы как bearer-токен. Токены создаются в панели аккаунта в разделе API Tokens, и каждому нужно дать имя. Используйте одно имя на окружение, например development, staging и production. Для ротации создайте новый токен, разверните его через менеджер секретов, проверьте, что запросы проходят, и затем выведите старый из обращения. Чтобы ограничить то, что может сделать утёкший токен, включите белый список IP (см. ниже), чтобы им могли пользоваться только адреса ваших серверов.

Секрет вебхуков, называемый персональным секретом, подписывает каждый вебхук через заголовок X-Signature. В документации по безопасности вебхуков сказано, что новый секрет вступает в силу для уведомлений вебхуков сразу. На стороне отправителя нельзя использовать два секрета одновременно, поэтому перекрытие должно быть на вашем получателе. Проверяйте подпись по новому секрету и по старому в течение короткого времени, затем удалите старый.

import { createHmac, timingSafeEqual } from "node:crypto";
// Accept the new secret and, during rotation only, the previous one
const secrets = [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET_PREVIOUS].filter(Boolean);
function signatureValid(txid, received) {
return secrets.some((secret) => {
const expected = createHmac("sha256", secret).update(txid).digest("base64");
return (
expected.length === received.length &&
timingSafeEqual(Buffer.from(expected), Buffer.from(received))
);
});
}

Уведомления, которые ваш сервер отклонил во время переключения, появляются в списке неудачных уведомлений. Chaingateway не повторяет их автоматически. Прочитайте список через GET /api/v2/{chain}/webhooks/notifications/failed и отправьте каждую запись повторно через POST /api/v2/{chain}/webhooks/notifications/{id}/retry. Руководство по гарантиям доставки вебхуков описывает это подробнее.

Пароли кошельков защищают адреса, которые вы создали с паролем. Его можно сменить через POST /api/v2/ethereum/addresses/{address}, который принимает old_password и new_password. Такой же маршрут есть для других сетей. Chaingateway не хранит пароли, поэтому сохраните новый пароль в менеджере секретов до смены. Утерянный пароль восстановить нельзя.

Что делает белый список IP в Chaingateway?

Белый список IP — это настройка аккаунта, которая ограничивает ваш API-ключ перечисленными вами адресами серверов. Он вышел 21 июня 2021 года. Вы включаете его в настройках панели аккаунта, затем вводите разрешённые адреса. Запрос с любого другого адреса отклоняется, даже если ключ верный, поэтому утёкший ключ бесполезен на любой машине, которой нет в вашем списке.

Добавьте адрес своего сервера при включении, иначе будут отклоняться и ваши собственные запросы. Указывайте публичный адрес, с которого ваш сервер выходит в интернет. Частные диапазоны, такие как 10.0.0.0/8 и 192.168.0.0/16, определены в RFC 1918 и никогда не доходят до API как источник запроса. За NAT-шлюзом указывайте адрес шлюза. Тогда разрешены все машины за ним, а не одна.

Белый список действует для запросов, которые вы отправляете в API. На вебхуки он не распространяется: они идут от Chaingateway к вашему endpoint. Проверяйте вебхуки по подписи, как описано выше.

Белый список и ротация ограничивают разное. Белый список ограничивает, откуда работает украденный ключ. Ротация ограничивает, как долго он работает. Используйте оба способа. Когда серверы переезжают на новые адреса, обновите список до переезда, чтобы не отклонялся ваш собственный трафик.

Когда статические API-ключи перестают быть разумными?

Статические ключи допустимы для внутренних инструментов с низким риском. Как только вы открываете API внешним партнёрам или работаете с финансовыми данными, переходите к аутентификации на основе OIDC или JWT с короткими сроками жизни. Начните с одного сервиса с низкой нагрузкой. Убедитесь, что автоматизация ротации выдерживает реальный трафик, и только потом расширяйте её. Политика ротации, которую действительно соблюдают, а не только рекомендуют, — одно из самых эффективных операционных изменений, которое может сделать служба безопасности.

Скриншот главной страницы Chaingateway с заголовком о едином blockchain API для крипто-платежей и вебхуков и кнопкой запуска 7-дневного бесплатного пробного периода

Chaingateway работает с Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Smart Chain и Arbitrum через один REST API и один уровень аутентификации, поэтому не нужно вести отдельный жизненный цикл учётных данных для каждой сети. Функция вебхуков отвечает за уведомления о депозитах. Тарифы начинаются с 49 € в месяц и опубликованы на странице цен, а 7-дневный пробный период не требует карты.

Источники

Рекомендуем

Создано с помощью BabyLoveGrowth для построения обратных ссылок

Часто задаваемые вопросы

Ротация API-ключа — это создание нового учётного данного на замену действующему с последующим отключением старого, когда все зависимые системы перешли на новый. Выполненная правильно, она идёт как автоматизированный цикл «создать, установить, проверить, завершить» с коротким перекрытием, в котором работают оба ключа.

Это зависит от риска. NIST IR 8587 говорит, что ключи подписи систем с высоким воздействием не должны использоваться дольше 90 дней. Для обычных API-ключей NIST числа не даёт, поэтому выбирайте интервал по объёму прав ключа. Для токенов CI/CD и для всего с широким доступом лучше короче.

Ротация ограничивает ущерб от утёкшего или украденного учётного данного, потому что сокращает время, в течение которого ключ действителен. OWASP относит долгоживущие секреты к NHI7 в своём Top 10 для не-человеческих идентичностей.

Автоматизируйте процесс с помощью менеджера секретов, следуйте шаблону «создать, установить, проверить, завершить» и держите переходное окно, в котором работают старый и новый ключ. Так избегается простой от одновременного переключения всех зависимых сервисов.

Да. Chaingateway подписывает вебхуки алгоритмом HMAC-SHA256 в заголовке X-Signature, поэтому вы можете проверить подлинность. Если вы меняете персональный секрет, новый секрет применяется сразу, поэтому ваш получатель должен некоторое время принимать оба секрета.

Как мы пишем эти статьи

Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.

C
Chaingateway Team
Эксперты по блокчейну

Команда Chaingateway стремится упростить интеграцию блокчейна для разработчиков по всему миру.