API спроектирован исходя из того, что каждый вызов имеет прямое финансовое влияние и может обращаться к чувствительным учётным данным сервера. Поэтому требования к безопасности существенно выше стандартных для REST.
Применяемые меры защиты
- HMAC-SHA256: Каждый запрос подписывается HMAC-SHA256 по методу, пути, временной метке, nonce и хешу тела. Верификация за константное время (hash_equals).
- AES-256-GCM: Секреты хранятся исключительно в виде шифротекста AES-256-GCM (libsodium). Мастер-ключ находится вне БД по пути /etc/kh-reseller-api/master.key.v{N}.
- Replay protection: Окно временной метки +-300с, кэш nonce 600с. Успешно подписанный запрос не может быть отправлен повторно.
- Scope-based authorization: Явный список разрешений для каждого ключа. Разрешения на запись и чувствительные разрешения должны быть включены явно.
- IP whitelist (optional): Опциональный белый список IP для каждого ключа (нотация CIDR, IPv4 и IPv6).
- Rate limit: Многоуровневое: на ключ (минута и день) и на IP (минута). Token bucket с допуском burst.
- Idempotency: Заказы и деструктивные действия с услугами требуют Idempotency-Key. 24-часовая защита от повторов при сетевых ретраях.
- Tenant isolation: Каждый запрос к БД жёстко фильтруется по идентификатору вашего аккаунта. Межарендный доступ невозможен по архитектуре.
- Tamper-evident audit log: Каждый запрос попадает в журнал аудита с цепочечным хешем (chain_hash[n] = sha256(chain_hash[n-1] || row_n)). Ретроактивное вмешательство обнаруживается по разрыву цепи хешей.
- Credentials.read alerting: Каждый вызов credentials.read создаёт отдельную запись в журнале аудита и опциональное подтверждение по email владельцу аккаунта.
- SSRF-guarded webhooks: URL вебхуков проверяются перед сохранением: только HTTPS, DNS-резолвинг должен возвращать только публичные IP (никаких RFC1918, никаких link-local).
Лучшие практики на вашей стороне
- Храните секрет в менеджере секретов (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password), никогда не в коде и не в git-репозитории.
- Регулярно ротируйте секрет (минимум раз в год или после смены персонала). Ротация одним кликом в портале, старый секрет немедленно становится недействительным.
- По одному отдельному ключу на каждый сценарий использования с минимальным разрешением (только чтение, если возможно). Никаких ключей "god-mode".
- Если ваша интеграция работает с фиксированных IP (облако, бастион): настройте белый список IP.
- Генерируйте Idempotency-Key на стороне сервера и сохраняйте его; не создавайте новый при каждой попытке. Рекомендация: UUIDv4 на каждый логический заказ.
- Настройте вебхук на собственный URL; как минимум отслеживайте order.created и credentials.read как поток событий.
Раскрытие уязвимостей
Сообщайте о проблемах безопасности конфиденциально на security@kernelhost.com. PGP-ключ — по запросу. Гарантированная реакция в течение 24 часов. Программа bug bounty в подготовке.
