Управляемые ключи (Managed Keys) в Stronghold

Managed Keys позволяют Stronghold использовать криптографические ключи, расположенные во внешней доверенной системе, например в HSM или внешнем KMS, без хранения приватного ключевого материала внутри самого Stronghold.

Такой подход полезен в сценариях, где:

• приватные ключи должны храниться вне Stronghold;
• операции подписи или шифрования должны выполняться внешней системой;
• есть требования по безопасности или соответствию, запрещающие экспорт ключевого материала.

В Stronghold managed key представляет собой именованную запись, управляемую через API sys/managed-keys/<TYPE>/<NAME>.

Как это работает

Stronghold хранит конфигурацию доступа к внешнему ключу, но не сам приватный ключ. Когда механизму секретов требуется операция подписи, проверки подписи, шифрования или расшифрования, он обращается к соответствующему managed key, а уже тот делегирует операцию внешнему backend-у.

Это означает, что:

• ключевой материал остаётся во внешней системе;
• Stronghold использует managed key как абстракцию поверх внешнего backend-а;
• несколько managed keys могут быть настроены для одного и того же backend-а, если нужны разные ключи или разные политики доступа.

Поддерживаемые backend-ы

В Stronghold поддерживаются следующие типы managed keys:

• pkcs11
• yandexcloudkms

pkcs11

Тип pkcs11 используется для работы с HSM и PKCS#11-совместимыми библиотеками. Конфигурация managed key этого типа ссылается на ранее объявленную kms_library "pkcs11" в серверной конфигурации Stronghold.

Типовой сценарий:

• настроить kms_library "pkcs11" в конфигурации сервера;
• зарегистрировать managed key через sys/managed-keys/pkcs11/<NAME>;
• при необходимости проверить доступность ключа через test/sign;
• разрешить использование ключа нужному mount-path.

Пример регистрации:

stronghold write sys/managed-keys/pkcs11/my-hsm-key library=softhsm token_label=managed-keys pin=1234 key_label=my-signing-key usages=sign,verify

Параметры pkcs11

Если mechanism не указан, ключ можно использовать только с уже существующим в HSM ключом, а генерация (allow_generate_key=true) недоступна.

Поддерживаемые механизмы

RSA и подписи PSS

Для RSA-ключей три RSA-механизма (CKM_RSA_PKCS, CKM_RSA_PKCS_OAEP, CKM_RSA_PKCS_PSS) лишь выбирают RSA-ключ: схему подписи (PKCS#1 v1.5 или RSA-PSS) для каждой операции определяет вызывающий механизм секретов, как в crypto/rsa языка Go. RSA-PSS используется с длиной соли, равной длине хеша. Подпись проверяется локально по открытому ключу, экспортированному из HSM.

• В PKI подпись RSA-PSS запрашивается параметром use_pss (при создании корневого и промежуточного CA, при подписи и в ролях). Если managed key поддерживает только подписи PSS, для издателя нужно задать revocation_signature_algorithm с одним из алгоритмов PSS, иначе построение CRL завершится ошибкой, в тексте которой упоминается PSS.
• В test/sign RSA-PSS запрашивается параметром use_pss=true. Подробнее — в разделе «Базовые операции».

Ключи ГОСТ

Ключи ГОСТ в HSM используются только для подписи и проверки подписи. Механизм определяет размер ключа:

• CKM_GOSTR3410 — 256-битные ключи;
• CKM_GOSTR3410_512 — 512-битные ключи.

Параметр curve задаёт профиль генерации ключа и должен соответствовать механизму:

• gost2001 или gost2012-256 для CKM_GOSTR3410;
• gost2012-512 для CKM_GOSTR3410_512.

Если curve не указан, профиль выбирается по механизму. Для подписи используется хеш-функция Стрибог: streebog-256 для 256-битных ключей и streebog-512 для 512-битных. Проверка подписи выполняется в HSM. При использовании ключа ГОСТ в pki алгоритм подписи выбирается по типу открытой части ключа. В transit managed key ГОСТ принимает только хеш-функцию Стрибог, соответствующую размеру ключа.

Пример регистрации ключа ГОСТ:

stronghold write sys/managed-keys/pkcs11/gost-ca-key library=rutoken token_label=managed-keys pin=12345678 key_label=my-gost-key mechanism=0x1201 curve=gost2012-256 usages=sign,verify

yandexcloudkms

Тип yandexcloudkms используется для интеграции с Yandex Cloud KMS.

Для конфигурации такого managed key используются параметры:

• kms_key_id
• oauth_token или service_account_key_json
• endpoint при необходимости

Для аутентификации Stronghold в Yandex Cloud KMS можно использовать один из следующих вариантов:

• oauth_token;
• service_account_key_json;
• сервисный аккаунт виртуальной машины в Yandex Cloud.

Если параметры oauth_token и service_account_key_json не заданы, Stronghold пытается использовать сервисный аккаунт виртуальной машины через стандартный механизм получения instance credentials. Это поведение аналогично типовым сценариям в Vault, где для облачных KMS могут использоваться учётные данные самой виртуальной машины.

Пример регистрации:

stronghold write sys/managed-keys/yandexcloudkms/my-yc-key kms_key_id=<KMS_KEY_ID> oauth_token=<OAUTH_TOKEN> usages=sign,verify

Где <KMS_KEY_ID> — идентификатор ключа Yandex Cloud KMS, <OAUTH_TOKEN> — OAuth-токен Yandex Cloud.

Пример использования сервисного аккаунта виртуальной машины:

stronghold write sys/managed-keys/yandexcloudkms/my-yc-key kms_key_id=<KMS_KEY_ID> usages=sign,verify

Какие механизмы секретов поддерживают Managed Keys

В Stronghold managed keys могут использовать:

• SSH
• PKI
• Transit

SSH

SSH secrets engine может использовать managed key как ключ центра сертификации (CA) и применять его для подписи SSH-сертификатов.

Это полезно, если SSH CA должен оставаться во внешнем HSM или внешнем KMS.

PKI

PKI secrets engine может использовать managed key для генерации и обслуживания корневых и промежуточных CA, а также для подписи сертификатов.

Это один из основных сценариев использования managed keys в Stronghold. Для PKI дополнительно важно разрешить managed key для конкретного PKI mount-а, если ключ не объявлен с any_mount=true.

Пример:

stronghold secrets tune -allowed-managed-keys=my-hsm-key pki/

Transit

Transit secrets engine может использовать managed key как внешний криптографический ключ.

В зависимости от возможностей backend-а и типа ключа это позволяет выполнять:

• подпись;
• проверку подписи;
• шифрование;
• расшифрование.

Для Transit managed key указывается при создании или ротации transit key.

Пространства имён и область видимости

Managed key привязан к конкретному namespace. Механизм секретов, который использует этот ключ, должен находиться в том же namespace, что и сам managed key.

Если ключ не объявлен с any_mount=true, его использование нужно явно разрешить для конкретного mount-path.

Базовые операции

Список managed keys заданного типа:

stronghold list sys/managed-keys/pkcs11

Чтение конфигурации ключа:

stronghold read sys/managed-keys/pkcs11/my-hsm-key

Проверка доступности ключа через тестовую подпись:

stronghold write sys/managed-keys/pkcs11/my-hsm-key/test/sign

Запрос test/sign принимает необязательные параметры:

• hash_algorithm — алгоритм хеширования для тестовой подписи. По умолчанию используется sha2-256; для ключей pkcs11 с механизмами ГОСТ — streebog-256 или streebog-512 в зависимости от механизма.
• use_pss — для RSA-ключей подписывать с использованием RSA-PSS. Для RSA-ключей yandexcloudkms, которые подписывают только с PSS, включён по умолчанию.

Удаление managed key:

stronghold delete sys/managed-keys/pkcs11/my-hsm-key

Практические рекомендации

• Используйте pkcs11, если ключи находятся в локальном или сетевом HSM с PKCS#11-библиотекой.
• Используйте yandexcloudkms, если ключи управляются в Yandex Cloud KMS.
• Ограничивайте usages только необходимыми операциями.
• Если ключ не должен быть доступен всем mount-ам, не включайте any_mount и явно настраивайте allowed-managed-keys.
• Перед подключением ключа к pki, ssh или transit проверяйте его через test/sign или другой подходящий тестовый сценарий.

Связанные разделы

• Механизм секретов PKI
• Механизм секретов Transit
• Подписанные SSH-сертификаты