Для улучшения работы сайта мы используем файлы cookies. Оставаясь на сайте, вы соглашаетесь с политикой обработки персональных данных.

Transit движок секретов (API)

Это документация API для движка секретов Transit StarVault. Для общих сведений о использовании и работе движка секретов Transit, пожалуйста, смотрите Механизм управления секретами Transit.

Данная документация предполагает, что движок секретов Transit включен по пути /transit в StarVault. Поскольку возможно включить движки секретов в любом месте, пожалуйста, обновите ваши API вызовы соответственно.

1. Создание ключа

Эта конечная точка создает новый именованный ключ шифрования указанного типа. Значения, установленные здесь, нельзя изменить после создания ключа.

Метод Путь

POST

/transit/keys/:name

1.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования, который нужно создать. Это указано как часть URL.

  • convergent_encryption (bool: false) - если включено, ключ будет поддерживать конвергентное шифрование, при котором одно и то же открытое сообщение создает один и тот же зашифрованный текст. Это требует, чтобы параметр derived был установлен в true. Когда этот параметр включен, каждое шифрование(/расшифровка/перенаправление/ключ данных) будет производить значение nonce вместо генерации его случайным образом.

  • derived (bool: false) - указывает, следует ли использовать производные ключи. Если включено, все запросы на шифрование/расшифровку для этого именованного ключа должны предоставлять контекст, который используется для вывода ключей.

  • exportable (bool: false) - позволяет ключам быть экспортируемыми. Это позволяет экспортировать все действительные ключи в кольце ключей. После установки это нельзя отключить.

  • allow_plaintext_backup (bool: false) - Если установлено, разрешает создание резервной копии именованного ключа в открытом формате. После установки это нельзя отключить.

  • type (string: "aes256-gcm96") - указывает тип ключа для создания. В настоящее время поддерживаемые типы:

    • aes128-gcm96 - AES-128, обернутый GCM, использующий 96-битный размер nonce AEAD (симметричный, поддерживает выведение и конвергентное шифрование)

    • aes256-gcm96 - AES-256, обернутый GCM, использующий 96-битный размер nonce AEAD (симметричный, поддерживает выведение и конвергентное шифрование, по умолчанию)

    • chacha20-poly1305 - ChaCha20-Poly1305 AEAD (симметричный, поддерживает выведение и конвергентное шифрование)

    • xchacha20-poly1305 - XChaCha20-Poly1305 AEAD (симметричный, поддерживает выведение и конвергентное шифрование)

    • ed25519 - ED25519 (ассиметричный, поддерживает выведение). При использовании выведения операция подписания с тем же контекстом выведет тот же ключ и подпись; это аналог подписи к convergent_encryption.

    • ecdsa-p256 - ECDSA с использованием эллиптической кривой P-256 (ассиметричный)

    • ecdsa-p384 - ECDSA с использованием эллиптической кривой P-384 (ассиметричный)

    • ecdsa-p521 - ECDSA с использованием эллиптической кривой P-521 (ассиметричный)

    • rsa-2048 - RSA с битовой длиной 2048 (ассиметричный)

    • rsa-3072 - RSA с битовой длиной 3072 (ассиметричный)

    • rsa-4096 - RSA с битовой длиной 4096 (ассиметричный)

    • hmac - HMAC (генерация HMAC, проверка)

  • key_size (int: "0", optional) - размер ключа в байтах для алгоритмов, которые допускают переменные размеры ключа. В настоящее время применимо только к HMAC, где он должен быть от 32 до 512 байт.

  • auto_rotate_period (duration: "0", optional) - период, в течение которого этот ключ должен автоматически ротироваться. Установка этого значения в "0" (по умолчанию) отключит автоматическую ротацию ключей. Это значение не может быть меньше одного часа. Использует строки формата длительности.

Пример тела запроса:
{
  "type": "ecdsa-p256",
  "derived": true
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key

2. Импорт ключа

Эта конечная точка импортирует существующий ключевой материал в новый управляемый поездом ключ шифрования. Чтобы импортировать ключевой материал в существующий ключ, смотрите конечную точку import_version/.

Эта функция поддерживает одну из двух форм:

  1. Импорт приватного/симметричного ключа, требующего установки параметров ciphertext, hash_function (и автоматически выведя публичный ключ);

  2. Импорт только публичного ключа, ограничивая операции, которые могут быть выполнены с этим ключом, и требуя только параметр public_key.

Остальные параметры (включая name, type, allow_rotation, derived, context, exportable, allow_plaintext_backup и auto_rotate_period) остаются одинаковыми для обеих версий этого вызова.

Метод Путь

POST

/transit/keys/:name/import

2.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования, который нужно создать. Это указано как часть URL.

  • ciphertext (string: <обязательный>) - закодированная в base64 строка, содержащая два значения: временный 256-битный AES ключ, обернутый ключом обертки, возвращенным StarVault, и шифрование импортируемого ключевого материала с использованием предоставленного AES ключа. Обернутый AES ключ должен быть первыми 512 байтами шифротекста, а зашифрованный ключевой материал должен быть оставшимися байтами. Смотрите раздел BYOK в Механизм управления секретами Transit для получения дополнительной информации о конструкции шифротекста. Если public_key установлен, это поле не требуется.

  • hash_function (string: "SHA256") - хэш-функция, используемая для этапа RSA-OAEP создания шифротекста. Поддерживаемые хэш-функции: SHA1, SHA224, SHA256, SHA384 и SHA512. Если не указано, по умолчанию используется хэш-функция SHA256.

  • type (string: <обязательный>) - указывает тип ключа для создания. В настоящее время поддерживаемые типы:

    • aes128-gcm96 - AES-128, обернутый GCM, использующий 96-битный размер nonce AEAD (симметричный, поддерживает выведение и конвергентное шифрование)

    • aes256-gcm96 - AES-256, обернутый GCM, использующий 96-битный размер nonce AEAD (симметричный, поддерживает выведение и конвергентное шифрование, по умолчанию)

    • chacha20-poly1305 - ChaCha20-Poly1305 AEAD (симметричный, поддерживает выведение и конвергентное шифрование)

    • xchacha20-poly1305 - XChaCha20-Poly1305 AEAD (симметричный, поддерживает выведение и конвергентное шифрование)

    • ed25519 - ED25519 (ассиметричный, поддерживает выведение). Когда используется выведение, операция подписания с тем же контекстом выведет тот же ключ и подпись; это аналог подписания для convergent_encryption.

    • ecdsa-p256 - ECDSA с использованием эллиптической кривой P-256 (ассиметричный)

    • ecdsa-p384 - ECDSA с использованием эллиптической кривой P-384 (ассиметричный)

    • ecdsa-p521 - ECDSA с использованием эллиптической кривой P-521 (ассиметричный)

    • rsa-2048 - RSA с размером ключа 2048 бит (ассиметричный)

    • rsa-3072 - RSA с размером ключа 3072 бит (ассиметричный)

    • rsa-4096 - RSA с размером ключа 4096 бит (ассиметричный)

  • public_key (string: "", optional) - открытый ключ PEM для импорта. Это ограничивает операции, доступные для этого ключа, до проверки и шифрования, в зависимости от типа и алгоритма ключа, так как закрытый ключ недоступен.

  • allow_rotation (bool: false) - если установлено в true, импортированный ключ может быть ротирован внутри StarVault, используя конечную точку rotate.

Как только импортированный ключ ротируется внутри StarVault, он больше не поддерживает импортирование ключевого материала. Только ключи, которые были предварительно импортированы в StarVault, могут импортировать новый ключевой материал из внешнего источника.

  • derived (bool: false) - указывает, следует ли использовать производные ключи. Если включено, все запросы на шифрование/расшифровку для этого именованного ключа должны предоставлять контекст, который используется для вывода ключей.

  • context (string: "") - строка, закодированная в base64, предоставляющая контекст для выведения ключей. Обязательно, если derived установлено в true.

  • exportable (bool: false) - позволяет ключам быть экспортируемыми. Это позволяет экспортировать все действительные ключи в кольце ключей. После установки это нельзя отключить.

  • allow_plaintext_backup (bool: false) - если установлено, разрешает создание резервной копии именованного ключа в открытом формате. После установки это нельзя отключить.

  • auto_rotate_period (duration: "0", optional) - период, в течение которого этот ключ должен автоматически ротироваться. Установка этого значения в "0" отключит автоматическую ротацию ключей. Это значение не может быть меньше одного часа.

Пример тела запроса:
{
  "type": "ed25519",
  "ciphertext": "... "
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key/import

3. Импорт версии ключа

Эта конечная точка импортирует новый ключевой материал в существующий импортированный ключ.

Смотрите описание и примечание в импорт ключа выше, касающееся импорта публичных и приватных ключей.

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

Метод Путь

POST

/transit/keys/:name/import_version

Ключи, чье содержание было сгенерировано StarVault, не поддерживают импортирование ключевого материала. Только ключи, которые были ранее импортированы в StarVault, могут импортировать новый ключевой материал из внешнего источника.

3.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования, который нужно создать. Это указано как часть URL.

  • ciphertext (string: <обязательный>) - закодированная в base64 строка, содержащая два значения: временный 256-битный AES ключ, обернутый ключом обертки, возвращенным StarVault, и шифрование импортируемого ключевого материала с использованием предоставленного AES ключа. Обернутый AES ключ должен быть первыми 512 байтами шифротекста, а зашифрованный ключевой материал должен быть оставшимися байтами. Смотрите раздел BYOK в Механизм управления секретами Transit для дополнительной информации о конструкции шифротекста.

  • hash_function (string: "SHA256") - хеш-функция, используемая для этапа RSA-OAEP создания шифротекста. Поддерживаемые хеш-функции: SHA1, SHA224, SHA256, SHA384 и SHA512. Если не указано, по умолчанию используется хеш-функция SHA256.

  • public_key (string: "", optional) - открытый ключ PEM для импорта. Это ограничивает операции, доступные для этого ключа, до проверки и шифрования, в зависимости от типа и алгоритма ключа, так как закрытый ключ недоступен.

  • version (int, optional) - версия ключа, которую нужно обновить; если не указано, будет создана новая версия, если не указан приватный ключ и отсутствует 'Latest' ключ, которому не соответствует приватный ключ.

Пример тела запроса:
{
  "ciphertext": "... "
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key/import_version

4. Получить обертывающий ключ

Эта конечная точка используется для получения обертывающего ключа, который следует использовать для импорта ключей. Возвращаемый ключ будет 4096-битным публичным ключом RSA.

Метод Путь

GET

/transit/wrapping_key
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/transit/wrapping_key
Пример ответа:
{
  "data": {
    "public_key": "..."
  }
}

5. Чтение ключа

Эта конечная точка возвращает информацию о именованном ключе шифрования. Объект keys показывает время создания каждой версии ключа; значения не являются самими ключами. В зависимости от типа ключа может быть возвращена различная информация, например, ассиметричный ключ будет возвращать свой публичный ключ в стандартном формате для этого типа.

Метод Путь

GET

/transit/keys/:name

5.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования для чтения. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transit/keys/my-key
Пример ответа:
{
  "data": {
    "type": "aes256-gcm96",
    "deletion_allowed": false,
    "derived": false,
    "exportable": false,
    "allow_plaintext_backup": false,
    "keys": {
      "1": 1442851412
    },
    "min_decryption_version": 1,
    "min_encryption_version": 0,
    "name": "foo",
    "supports_encryption": true,
    "supports_decryption": true,
    "supports_derivation": true,
    "supports_signing": false,
    "imported": false
  }
}

Атрибут keys перечисляет каждую версию ключа и время создания ключа в секундах с начала эпохи Unix. Примерный ответ показывает ключ, созданный 22 сентября 2015 года в 19:50:12 по GMT, который не был ротацией.

Поля supports_encryption, supports_decryption, supports_derivation и supports_signing определяются типом ключа и указывают, какие операции могут быть выполнены с ним.

6. Список ключей

Эта конечная точка возвращает список ключей. Возвращаются только имена ключей (не сами ключи).

Метод Путь

LIST

/transit/keys

6.1. Параметры

  • after (string: "") - необязательная запись, чтобы начать перечисление после для постраничной разбивки; не обязательно должна существовать.

  • limit (int: 0) - необязательное количество записей для возврата; по умолчанию возвращаются все записи.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/transit/keys
Пример ответа:
{
  "data": {
    "keys": ["foo", "bar"]
  },
  "lease_duration": 0,
  "lease_id": "",
  "renewable": false
}

7. Удаление ключа

Эта конечная точка удаляет именованный ключ шифрования. Данные, зашифрованные с использованием именованного ключа, больше не могут быть расшифрованы. Поскольку это потенциально катастрофическая операция, поле deletion_allowed должно быть установлено в ключе на конечной точке /config.

Метод Путь

DELETE

/transit/keys/:name

7.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования для удаления. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/transit/keys/my-key

8. Обновление конфигурации ключа

Эта конечная точка позволяет изменять значения конфигурации для заданного ключа (эти значения возвращаются во время операции чтения для именованного ключа).

Метод Путь

POST

/transit/keys/:name/config

8.1. Параметры

  • min_decryption_version (int: 0) - указывает минимальную версию шифротекста, разрешенную для расшифровки. Настройка этого параметра в рамках политики ротации ключей может предотвратить расшифровку старых копий шифротекста, если они попадут в чужие руки. Для подписей это значение контролирует минимальную версию подписи, которая может быть проверена. Для HMAC это контролирует минимальную версию ключа, разрешенную для использования в качестве ключа для проверки.

  • min_encryption_version (int: 0) - указывает минимальную версию ключа, которая может использоваться для шифрования открытого текста, подписания полезных нагрузок или генерации HMAC. Должно быть 0 (что будет использовать последнюю версию) или значение, равное или превышающее min_decryption_version.

  • deletion_allowed (bool: false) - указывает, разрешено ли удаление ключа.

  • exportable (bool: false) - позволяет ключам быть экспортируемыми. Это позволяет экспортировать все действительные ключи в кольце ключей. После установки это нельзя отключить.

  • allow_plaintext_backup (bool: false) - если установлено, разрешает создание резервной копии именованного ключа в открытом формате. После установки это нельзя отключить.

  • auto_rotate_period (duration: "", optional) - период, в течение которого этот ключ должен автоматически ротироваться. Установка этого значения в "0" отключит автоматическую ротацию ключей. Это значение не может быть меньше одного часа. Если значение не указано, период остается неизменным. Использует строки формата длительности.

Пример тела запроса:
{
  "deletion_allowed": true
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key/config

9. Ротация ключа

Эта конечная точка вращает версию именованного ключа. После ротации новые запросы на открытый текст будут шифроваться с помощью новой версии ключа. Чтобы обновить шифротекст, чтобы он был зашифрован с помощью последней версии ключа, используйте конечную точку rewrap. Это поддерживается только ключами, которые поддерживают операции шифрования и расшифрования.

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

Для импортированных ключей ротация поддерживается только если поле allow_rotation было установлено в true при импорте. Как только импортированный ключ будет ротирован внутри StarVault, он не будет поддерживать дальнейшие операции импорта.
Метод Путь

POST

/transit/keys/:name/rotate

9.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования для ротации. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/transit/keys/my-key/rotate

10. Мягкое удаление ключа

Эта конечная точка мягко удаляет именованный ключ шифрования, позволяя его восстановить позже, если это удаление было сделано по ошибке. Это не зависит от значения deletion_allowed.

Следующие операции не будут работать с ключом :name, пока ключ не будет восстановлен:

  • Экспорт BYOK, как исходным, так и целевым ключом (/transit/byok-export/:dest/:name и /transit/byok-export/:name/:src),

  • Экспорт (/transit/export/:key_type/:name),

  • Шифрование и расшифровка (/transit/encrypt/:name и /transit/decrypt/:name),

  • Подписание и верификация, включая HMAC ключи (/transit/sign/:name, /transit/hmac/:name и /transit/verify/:name), и

  • Ротация указанного ключа (/transit/keys/:name/rotate).

Тем не менее, этот ключ по-прежнему может быть обновлен, сохранен, прочитан и появится в операциях списка.

Метод Путь

DELETE

/transit/keys/:name/soft-delete

10.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования для мягкого удаления. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/transit/keys/my-key/soft-delete

11. Восстановление мягко удаленного ключа

Эта конечная точка восстанавливает мягко удаленный именованный ключ шифрования, позволяя его использовать снова.

Метод Путь

POST

/transit/keys/:name/soft-delete-restore

11.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования для восстановления из мягкого удаления. Это указано как часть URL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/transit/keys/my-key/soft-delete-restore

12. Безопасный экспорт ключа

Эта конечная точка возвращает обернутую копию ключа source, защищенную ключом destination, с использованием метода BYOK, принятого конечной точкой /transit/keys/:name/import. Это позволяет оператору, используя два отдельных экземпляра StarVault, защитить установленный общий ключевой материал, не раскрывая ни один из ключей в открытом виде и не требуя ручного импорта BYOK с использованием утилиты CLI.

Метод Путь

GET

/transit/byok-export/:destination/:source(/:version)

12.1. Параметры

  • destination (string: <обязательный>) - указывает имя ключа, чтобы зашифровать ключ source: это обычно другой монтирование или оберточный ключ кластера (из /transit/wrapping_key). Это указано как часть URL.

этот тип ключа назначения должен быть типом ключа RSA.

  • source (string: <обязательный>) - указывает исходный ключ для шифрования, чтобы скопировать (зашифрованный) в другой кластер. Это указано как часть URL.

  • version (string: "") - указывает версию исходного ключа, которую нужно обернуть. Если опущено, будут возвращены все версии ключа. Это указано как часть URL. Если версия установлена в latest, будет возвращен текущий ключ.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transit/byok-export/wrapping-key/to-be-shared-key/1
Пример ответа:
{
  "data": {
    "name": "foo",
    "keys": {
      "1": "H/0T+CKQ8I82KJWpPk ... дополнительные данные опущены..."
    }
  }
}

13. Экспорт ключа

Эта конечная точка возвращает именованный ключ. Объект keys показывает значение ключа для каждой версии. Если указан version, будет возвращена конкретная версия. Если указано latest, будет предоставлен текущий ключ. В зависимости от типа ключа может быть возвращена различная информация. Ключ должен быть экспортируемым, чтобы поддерживать эту операцию, и версия должна оставаться действительной.

Метод Путь

GET

/transit/export/:key_type/:name(/:version)

13.1. Параметры

  • key_type (string: <обязательный>) - указывает тип ключа для экспорта. Это указано как часть URL. Допустимые значения:

    • encryption-key

    • signing-key

    • hmac-key

    • public-key, чтобы вернуть соответствующие публичные ключи ассиметричных ключей (EC с NIST P-кривыми или Ed25519 и RSA).

  • name (string: <обязательный>) - указывает имя ключа, для которого нужно прочитать информацию. Это указано как часть URL.

  • version (string: "") - указывает версию ключа для чтения. Если опущено, будут возвращены все версии ключа. Это указано как часть URL. Если версия установлена в latest, будет возвращен текущий ключ.

  • format (string: "") - указывает формат экспортируемого ключа. Пустая строка сохраняет существующее поведение, при этом формат уникален для каждого типа ключа (ключи, закодированные в формате base64 для симметричных ключей или ключей Ed25519, PKCS#1 для RSA закрытых ключей, SEC 1 для EC закрытых ключей и формат PKIX для RSA или EC публичных ключей). Формат raw всегда возвращает ключ в виде закодированного в base64 сырого ключа (применимо только к симметричным ключам и ключам Ed25519). Форматы der и pem всегда возвращают объект в формате PKIX (SubjectPublicKeyInfo) или PrivateKeyInfo для ассиметричных ключей.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transit/export/encryption-key/my-key/1
Пример ответа:
{
  "data": {
    "name": "foo",
    "keys": {
      "1": "eyXYGHbTmugUJn6EtYD/yVEoF6pCxm4R/cMEutUm3MY=",
      "2": "Euzymqx6iXjS3/NuGKDCiM2Ev6wdhnU+rBiKnJ7YpHE="
    }
  }
}

14. Запись конфигурации ключей

Эта конечная точка управляет глобальной конфигурацией для всех ключей. Это позволяет удалить возможность upsert конечной точки /encrypt/:key, предотвращая создание новых ключей, если они не существуют.

Метод Путь

POST

/transit/config/keys

14.1. Параметры

  • disable_upsert (bool: false) - указывает, следует ли отключить upsert для шифрования (автоматическое создание неизвестных ключей).

Пример тела запроса:
{
  "disable_upsert": true
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/config/keys
Пример ответа:
{
  "data": {
    "disable_upsert": true
  }
}

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

Эта конечная точка поддерживает глобальную конфигурацию для всех ключей. Это позволяет удалить возможность upsert конечной точки /encrypt/:key, предотвращая создание новых ключей, если они не существуют.

Метод Путь

GET

/transit/config/keys
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transit/config/keys
Пример ответа:
{
  "data": {
    "disable_upsert": false
  }
}

16. Шифрование данных

Эта конечная точка шифрует предоставленный открытый текст с использованием именованного ключа. Этот путь поддерживает возможности политик create и update, как указано: если пользователь имеет возможность create для этой конечной точки в своих политиках, и ключ не существует, он будет вставлен с умолчательными значениями (необходимость выведения ключа зависит от того, пустой ли параметр контекста или нет). Если у пользователя есть только возможность update и ключ не существует, будет возвращена ошибка.

Если вставка запрещена глобальной конфигурацией ключей, create запросы будут вести себя как update запросы.
Метод Путь

POST

/transit/encrypt/:name

16.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования, против которого нужно шифровать. Это указано как часть URL.

  • plaintext (string: <обязательный>) - указывает закодированный в base64 открытый текст, который необходимо зашифровать.

  • associated_data (string: "") - указывает закодированные в base64 сопутствующие данные (также известные как дополнительные данные или AAD), которые также должны быть аутентифицированы с AEAD шифрами (aes128-gcm96, aes256-gcm, chacha20-poly1305 и xchacha20-poly1305).

  • context (string: "") - указывает закодированный в base64 контекст для вывода ключей. Обязательно, если выведение ключей включено для этого ключа.

  • key_version (int: 0) - указывает версию ключа для использования при шифровании. Если не указано, используется последняя версия. Должно быть больше или равно минимальной версии шифрования ключа, если она установлена.

  • nonce (string: "") - указывает закодированное в base64 значение nonce. Значение должно быть ровно 96 бит (12 байт) в длину, и пользователь должен убедиться что для любого данного контекста (и, следовательно, для любого данного ключа шифрования) это значение nonce никогда не используется повторно.

  • reference (string: "") - строка, предоставленная пользователем, которая будет присутствовать в поле reference на соответствующем элементе batch_results в ответе, чтобы помочь понять, какой результат соответствует конкретному вводу. Действительно только на пакетных запросах при использовании ‘batch_input’ ниже.

  • batch_input (array<object>: nil) - указывает список элементов, которые будут зашифрованы в одной партии. Когда этот параметр установлен, если также установлены параметры 'plaintext' и 'context', они будут проигнорированы. Любой выход партии будет сохранять порядок входных данных партии. Формат для ввода выглядит так:

    [
  {
    "context": "c2FtcGxlY29udGV4dA==",
    "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA=="
  },
  {
    "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=",
    "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA=="
  }
]

  • type (string: "aes256-gcm96") - этот параметр требуется, когда ожидается создание ключа шифрования. При выполнении операции вставки устанавливается тип ключа для создания.

  • convergent_encryption (string: "") - этот параметр будет использоваться только при ожидании создания ключа. Указывает, следует ли поддерживать конвергентное шифрование. Это поддерживается только при использовании ключа с включенной поддержкой вывода ключей и будет требовать, чтобы все запросы содержали как контекст, так и 96-битный (12-байтовый) nonce для AES и ChaCha20 или 192-битный (24-байтовый) для nonce XChaCha20. Указанный nonce будет использоваться вместо случайно сгенерированного nonce. Таким образом, когда предоставляются тот же контекст и nonce, создается один и тот же зашифрованный текст. Очень важно, чтобы при использовании этого режима вы гарантировали, что все nonce уникальны для данного контекста. Несоблюдение этого условия сильно повлияет на безопасность зашифрованного текста.

  • partial_failure_response_code (int: 400) Обычно, если элемент партии не удается зашифровать из-за плохого ввода, но другие элементы партии успешны, код HTTP ответа составляет 400 (Некорректный запрос). Некоторые приложения могут захотеть обрабатывать частичные сбои иначе. Указание этого параметра возвращает указанный код ответа вместо кода статуса сбоя в этом случае. Если все значения заканчиваются неудачей, все равно возвращается код ошибки. Будьте осторожны: некоторые сбои (такие как сбой при расшифровке) могут указывать на нарушение безопасности и не должны быть проигнорированы.

Пример тела запроса:
{
  "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA="
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/encrypt/my-key
Пример ответа:
{
  "data": {
    "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA="
  }
}

17. Расшифровка данных

Эта конечная точка расшифровывает предоставленный шифротекст, используя именованный ключ.

Метод Путь

POST

/transit/decrypt/:name

17.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования, по которому нужно расшифровать. Это указано как часть URL.

  • ciphertext (string: <обязательный>) - указывает шифротекст для расшифровки.

  • associated_data (string: "") - указывает кодированную в base64 сопутствующую информацию (также известную как дополнительные данные или AAD), которая также будет аутентифицирована с AEAD шифрами (aes128-gcm96, aes256-gcm, chacha20-poly1305, и xchacha20-poly1305).

  • context (string: "") - указывает закодированный в base64 контекст для производства ключей. Это требуется, если вывод ключей включен.

  • nonce (string: "") - указывает закодированное в base64 значение nonce, использованное при шифровании.

  • reference (string: "") - строка, предоставленная пользователем, которая будет присутствовать в поле reference на соответствующем элементе batch_results в ответе для помощи в понимании, какой результат соответствует конкретному вводу. Действительно только на пакетных запросах при использовании «batch_input» ниже.

  • batch_input (array<object>: nil) - указывает список элементов, которые будут расшифрованы в одной партии. Когда этот параметр установлен, если параметры 'ciphertext' и 'context' также установлены, они будут проигнорированы. Выход каждой партии сохранит порядок входных данных. Формат входных данных выглядит так:

    [
  {
    "context": "c2FtcGxlY29udGV4dA==",
    "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI="
  },
  {
    "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=",
    "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA="
  }
]

  • partial_failure_response_code (int: 400) Обычно, если элемент партии не удается зашифровать из-за плохого ввода, но другие элементы партии успешны, код HTTP ответа составляет 400 (Некорректный запрос). Некоторые приложения могут захотеть обрабатывать частичные сбои иначе. Указание этого параметра возвращает указанный код ответа вместо кода статуса сбоя в этом случае. Если все значения заканчиваются неудачей, все равно возвращается код ошибки. Будьте осторожны: некоторые сбои (такие как сбой при расшифровке) могут указывать на нарушение безопасности и не должны быть проигнорированы.

Пример тела запроса:
{
  "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA="
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/decrypt/my-key
Пример ответа:
{
  "data": {
    "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo="
  }
}

18. Перепаковка данных

Эта конечная точка перепаковывает предоставленный шифротекст, используя последнюю версию именованного ключа. Поскольку это никогда не возвращает открытый текст, можно поручить эту функциональность ненадежным пользователям или скриптам.

Метод Путь

POST

/transit/rewrap/:name

18.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования для перепаковки. Это указано как часть URL.

  • ciphertext (string: <обязательный>) - указывает шифротекст для перепаковки.

  • context (string: "") - указывает закодированный в base64 контекст для ключа вывода. Это требуется, если включено преобразование ключей.

  • key_version (int: 0) - указывает версию ключа, которую нужно использовать для операции. Если не установлено, используется последняя версия. Должно быть больше или равно минимальной версии шифрования ключа, если она установлена.

  • nonce (string: "") - указывает закодированное в base64 значение nonce, использованное при шифровании.

  • reference (string: "") - строка, предоставленная пользователем, которая будет присутствовать в поле reference на соответствующем элементе batch_results в ответе, чтобы помочь понять какой результат соответствует конкретному вводу. Действительно только на пакетных запросах при использовании ‘batch_input’ ниже.

  • batch_input (array<object>: nil) - указывает список элементов, которые будут перепакованы в одной партии. Когда этот параметр установлен, если параметры 'ciphertext' и 'context' также установлены, они будут проигнорированы. Выход каждой партии сохранит порядок входных данных. Формат входных данных выглядит так:

    [
  {
    "context": "c2FtcGxlY29udGV4dA==",
    "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI="
  },
  {
    "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=",
    "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA="
  }
]
Пример тела запроса:
{
  "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA="
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/rewrap/my-key
Пример ответа:
{
  "data": {
    "ciphertext": "vault:v2:abcdefgh"
  }
}

19. Генерация ключа данных

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

Метод Путь

POST

/transit/datakey/:type/:name

19.1. Параметры

  • type (string: <обязательный>) - указывает тип ключа для генерации. Если plaintext, открытый текст ключа будет возвращен вместе с шифротекстом. Если wrapped, будет возвращено только значение шифротекста. Это указано как часть URL.

  • name (string: <обязательный>) - указывает имя ключа шифрования, который нужно использовать для шифрования ключа данных. Это указано как часть URL.

  • context (string: "") - указывает контекст для выведения ключей, предоставленный как строка, закодированная в base64. Это необходимо, если вывод ключей включен.

  • nonce (string: "") - указывает значение nonce, предоставленное в закодированном в base64 виде. Значение должно быть ровно 96 бит (12 байт) в длину, и пользователь должен убедиться что для любого данного контекста (и, следовательно, любого данного ключа шифрования) это значение nonce никогда не используется повторно.

  • bits (int: 256) - указывает количество бит в желаемом ключе. Может быть 128, 256 или 512.

Пример тела запроса:
{
  "context": "Ab3=="
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/datakey/plaintext/my-key
Пример ответа:
{
  "data": {
    "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=",
    "ciphertext": "vault:v1:abcdefgh"
  }
}

20. Генерация случайных байтов

Эта конечная точка возвращает качественные случайные байты указанной длины.

Метод Путь

POST

/transit/random(/:source)(/:bytes)

20.1. Параметры

  • bytes (int: 32) - указывает количество байт для возврата. Это значение может быть указано либо в теле запроса, либо как часть URL.

  • format (string: "base64") - указывает кодировку выходных данных. Допустимые опции

    • hex или base64.

  • source (string: "platform") - указывает источник запрашиваемых байтов. platform, по умолчанию, получает байты из источника энтропии платформы. all смешивает байты из всех доступных источников.

Пример тела запроса:
{
  "format": "hex"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/random/164
Пример ответа:
{
  "data": {
    "random_bytes": "dGhlIHF1aWNrIGJyb3duIGZveAo="
  }
}

21. Хеширование данных

Эта конечная точка возвращает криптографический хеш заданных данных с использованием указанного алгоритма.

Метод Путь

POST

/transit/hash(/:algorithm)

21.1. Параметры

  • algorithm (string: "sha2-256") - указывает хеш-алгоритм для использования. Это также может быть указано как часть URL. В настоящее время поддерживаемые алгоритмы:

    • sha2-224

    • sha2-256

    • sha2-384

    • sha2-512

    • sha3-224

    • sha3-256

    • sha3-384

    • sha3-512

В режиме FIPS 140-2 следующие алгоритмы не сертифицированы и, следовательно, не должны использоваться: sha3-224, sha3-256, sha3-384 и sha3-512.

  • input (string: <обязательный>) - указывает закодированные в base64 входные данные.

  • format (string: "hex") - указывает кодировку выходных данных. Это может быть либо hex, либо base64.

Пример тела запроса:
{
  "input": "adba32=="
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/hash/sha2-512
Пример ответа:
{
  "data": {
    "sum": "dGhlIHF1aWNrIGJyb3duIGZveAo="
  }
}

22. Генерация HMAC

Эта конечная точка возвращает дайджест заданных данных, используя указанный хеш алгоритм и именованный ключ. Ключ может быть любого типа, поддерживаемого transit, так как каждая версия ключа transit имеет независимый, случайный 256-битный HMAC секретный ключ. Если ключ имеет тип, поддерживающий ротацию, будет использоваться последняя (текущая) версия.

Метод Путь

POST

/transit/hmac/:name(/:algorithm)

22.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования, для которого будет генерироваться HMAC. Это указано как часть URL.

  • key_version (int: 0) - указывает версию ключа для использования в операции. Если не указано, будет использоваться последняя версия. Должно быть больше или равно минимальной версии шифрования ключа, если она указана.

  • algorithm (string: "sha2-256") - указывает хеш алгоритм для использования. Это также можно указать как часть URL. В настоящее время поддерживаемые алгоритмы:

    • sha2-224

    • sha2-256

    • sha2-384

    • sha2-512

    • sha3-224

    • sha3-256

    • sha3-384

    • sha3-512

В режиме FIPS 140-2 следующие алгоритмы не сертифицированы и, следовательно, не должны использоваться: sha3-224, sha3-256, sha3-384 и sha3-512.

  • input (string: "") - указывает кодированные в base64 входные данные. Один из input или batch_input должен быть представлен.

  • reference (string: "") - строка, предоставленная пользователем, которая будет присутствовать в поле reference на соответствующем элементе batch_results в ответе, чтобы помочь понять, какой результат соответствует конкретному вводу. Действительно только на пакетных запросах при использовании ‘batch_input’ ниже.

  • batch_input (array<object>: nil) - указывает список элементов для обработки. Когда этот параметр установлен, любые предоставленные параметры 'input' или 'context' будут игнорироваться. Ответы возвращаются в массиве 'batch_results' в элементе 'data' ответа. Любой выход партии будет сохранять порядок входных данных. Если значение данных ввода элемента недействительно, соответствующий элемент в 'batch_results' будет иметь ключ 'error' с описанием ошибки. Формат для batch_input:

    {
  "batch_input": [
    {
      "input": "adba32=="
    },
    {
      "input": "aGVsbG8gd29ybGQuCg=="
    }
  ]
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/hmac/my-key/sha2-512
Пример тела запроса:
{
  "input": "adba32=="
}
Пример ответа:
{
  "data": {
    "hmac": "dGhlIHF1aWNrIGJyb3duIGZveAo="
  }
}
Пример тела запроса:
{
  "batch_input": [
    {
      "input": "adba32=="
    },
    {
      "input": "adba32=="
    },
    {},
    {
      "input": ""
    }
  ]
}
Пример ответа для batch_input:
{
  "data": {
    "batch_results": [
      {
        "hmac": "vault:v1:1jFhRYWHiddSKgEFyVRpX8ieX7UU+748NBwHKecXE3hnGBoAxrfgoD5U0yAvji7b5X6V1fP"
      },
      {
        "hmac": "vault:v1:1jFhRYWHiddSKgEFyVRpX8ieX7UU+748NBwHKecXE3hnGBoAxrfgoD5U0yAvji7b5X6V1fP"
      },
      {
        "error": "missing input for HMAC"
      },
      {
        "hmac": "vault:v1:/wsSP6iQ9ECO9RRkefKLXey9sDntzSjoiW0vBrWfUsYB0ISroyC6plUt/jN7gcOv9O+Ecow"
      }
    ]
  }
}

23. Подписание данных

Эта конечная точка возвращает криптографическую подпись заданных данных, используя именованный ключ и указанный хеш алгоритм. Ключ должен быть типа, который поддерживает подписание.

Метод Путь

POST

/transit/sign/:name(/:hash_algorithm)

23.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа шифрования, который будет использоваться для подписи. Это указано как часть URL.

  • key_version (int: 0) - указывает версию ключа для использования при подписании. Если не установлено, используется последняя версия. Должно быть больше или равно минимальной версии шифрования ключа, если она установлена.

  • hash_algorithm (string: "sha2-256") - указывает хеш алгоритм, используемый для поддерживаемых типов ключей (примечание: не включая ed25519, который указывает свой собственный хеш алгоритм). Это также можно указать как часть URL.

В настоящее время поддерживаемые алгоритмы: sha1 sha2-224 sha2-256 sha2-384 sha2-512 sha3-224 sha3-256 sha3-384 sha3-512 none

В режиме FIPS 140-2 следующие алгоритмы не сертифицированы и, следовательно, не должны использоваться: sha3-224, sha3-256, sha3-384 и sha3-512.

sha1 должен рассматриваться как компрометированный алгоритм, и его следует использовать только для устаревших приложений. Подписи с использованием SHA-1 могут быть заблокированы операторами путем назначения следующей политики соответствующему именованному ключу:

 
  path "/transit/sign/:name/sha1" {
    capabilities = ["deny"]
  }

Использование hash_algorithm=none требует установки prehashed=true и signature_algorithm=pkcs1v15. Это генерирует подписи типа PKCSv1_5_NoOID вместо типа подписи PKCSv1_5_DERnull, который обычно создается. См. RFC 3447 Раздел 9.2.

  • input (string: "") - указывает закодированные в base64 входные данные. Один из input или batch_input должен быть представлен.

  • signature (string: "") - указывает выходную подпись из функции /transit/sign. Это должно быть указано либо это, либо hmac.

  • hmac (string: "") - указывает выходной HMAC из функции /transit/hmac. Это должно быть указано либо это, либо signature.

  • reference (string: "") - строка, предоставленная пользователем, которая будет присутствовать в поле reference на соответствующем элементе batch_results в ответе, чтобы помочь понять какой результат соответствует определенному вводу. Действительно только на пакетных запросах при использовании 'batch_input' ниже.

  • batch_input (array<object>: nil) - указывает список элементов для обработки. Когда этот параметр установлен, любые предоставленные параметры 'input', 'hmac' или 'signature' будут игнорироваться. Элементы batch_input должны содержать параметр 'input' и либо параметр 'hmac', либо 'signature'. Все элементы в пакете должны последовательно предоставлять либо параметры 'hmac', либо 'signature'. Ошибкой будет, если некоторые элементы будут предоставлять 'hmac', а другие 'signature'. Ответы возвращаются в массиве 'batch_results' в элементе 'data' ответа. Любой выход пакета будет сохранять порядок входных данных пакета. Если значение данных ввода элемента недействительно, соответствующий элемент в 'batch_results' будет иметь ключ 'error' с описанием ошибки. Формат для batch_input:

    {
  "batch_input": [
    {
      "input": "adba32==",
      "context": "abcd"
    },
    {
      "input": "aGVsbG8gd29ybGQuCg==",
      "context": "efgh"
    }
  ]
}

  • context (string: "") - закодированный в base64 контекст для вывода ключа. Обязательно, если вывод ключа включен; в настоящее время доступно только с ключами ed25519.

  • prehashed (bool: false) - установите в true, когда вход уже хеширован. Если тип ключа rsa-2048, rsa-3072 или rsa-4096, то алгоритм, используемый для хеширования входа, должен быть указан параметром hash_algorithm. То же самое что и значение, которое будет подписано, должно быть представлено как закодированное в base64 представление точных двоичных данных, которые вы хотите подписать, и при установки параметр 'input' должен быть представлен в виде закодированных в base64 двоичных хешированных данных, а не в шестнадцатеричном формате. (Например, на командной строке вы можете получить соответствующий ввод с помощью openssl dgst -sha256 -binary | base64.)

  • signature_algorithm (string: "pss") - при использовании RSA ключа, указывает алгоритм подписи RSA, который будет использоваться для подписи. Поддерживаемые типы подписей:

    • pss

    • pkcs1v15

  • marshaling_algorithm (string: "asn1") - указывает способ, которым подпись была в оригинале. Это в настоящее время применимо только к ключам ECDSA. Поддерживаемые типы:

    • asn1: по умолчанию, используемое OpenSSL и X.509

    • jws: версия, используемая JWS (и, следовательно, для JWT). Выбор этого также ожидал бы, что кодировка ввода будет безопасна для URL Base64, а не стандартная Base64-кодировка.

  • salt_length (string: "auto") - длина соли, используемой для подписи. Это в настоящее время применимо только к схеме подписи RSA PSS. Опции:

    • auto: по умолчанию используемое Golang (делает соль как можно большей при подписании)

    • hash: делает длину соли равной длине хеша, используемого в подписи

    • Целое число между минимальной и максимальной допустимой длинами соли для данного размера ключа RSA.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/sign/my-key/sha2-512
Пример тела запроса:
{
  "input": "abcd13==",
  "signature": "vault:v1:MEUCIQCyb869d7KWuA..."
}
Пример ответа:
{
  "data": {
    "valid": true
  }
}
Пример тела запроса:
{
  "batch_input": [
    {
      "input": "adba32==",
      "context": "abcd",
      "signature": "vault:v1:3hBwA88lnuAVJqb5rCCEstzKYaBTeSdejk356BTCE/nKwySOhzQH3mWCvJZwbRptNGa7ia5ykosYYdJz+aIKDA=="
    },
    {
      "input": "adba32==",
      "context": "efgh",
      "signature": "vault:v1:3hBwA88lnuAVJqb5rCCEstzKYaBTeSdejk356BTCE/nKwySOhzQH3mWCvJZwbRptNGa7ia5ykosYYdJz+aIKDA=="
    },
    {
      "input": "",
      "context": "abcd",
      "signature": "vault:v1:C/pxm5V1RI6kqudLdbLdj5Bpm2P38FKgvxoV69oNXphvJukRcQIqjZO793jCa2JPYPG21Y7vquDWy/Ff4Ma4AQ=="
    }
  ]
}
Пример ответа для batch_input:
{
  "data": {
    "batch_results": [
      {
        "valid": true
      },
      {
        "valid": false
      },
      {
        "valid": true
      }
    ]
  }
}

24. Резервная копия ключа

Эта конечная точка возвращает резервную копию названного ключа в открытом виде. Резервная копия содержит все данные конфигурации и ключи всех версий, а также ключ HMAC. Ответ от этой конечной точки можно использовать с конечной точкой /restore для восстановления ключа.

Метод Путь

GET

/transit/backup/:name

24.1. Параметры

  • name (string: <обязательный>) - имя ключа.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transit/backup/aes
Пример ответа:
{
  "data": {
    "backup": "eyJwb2xpY3kiOnsibmFtZSI6ImFlcyIsImtleXMiOnsiMSI6eyJrZXkiOiJXK3k4Z0dOMHdiTDJLOU95NXFPN1laMGtjdzMvR0ZiNWM4STBzdlNMMnFNPSIsImhtYWNfa2V5IjoiUDBTcjh1YTJaZERNUTdPd2h4RGp1Z0U5d0JSR3Q2QXl6K0t4TzN5Z2M5ST0iLCJ0aW1lIjoiMjAxNy0xMi0wOFQxMTo1MDowOC42MTM4MzctMDU6MDAiLCJlY194IjpudWxsLCJlY195IjpudWxsLCJlY19kIjpudWxsLCJyc2Ffa2V5IjpudWxsLCJwdWJsaWNfa2V5IjoiIiwiY3JlYXRpb25fdGltZSI6MTUxMjc1MTgwOH19LCJkZXJpdmVkIjpmYWxzZSwia2RmIjowLCJjb252ZXJnZW50X2VuY3J5cHRpb24iOmZhbHNlLCJleHBvcnRhYmxlIjpmYWxzZSwibWluX2RlY3J5cHRpb25fdmVyc2lvbiI6MSwibWluX2VuY3J5cHRpb25fdmVyc2lvbiI6MCwibGF0ZXN0X3ZlcnNpb24iOjEsImFyY2hpdmVfdmVyc2lvbiI6MSwiZGVsZXRpb25fYWxsb3dlZCI6ZmFsc2UsImNvbnZlcmdlbnRfdmVyc2lvbiI6MCwidHlwZSI6MCwiYmFja3VwX2luZm8iOnsidGltZSI6IjIwMTctMTItMDhUMTE6NTA6MjkuMjI4MTU3LTA1OjAwIiwidmVyc2lvbiI6MX0sInJlc3RvcmVfaW5mbyI6bnVsbH0sImFyY2hpdmVkX2tleXMiOnsia2V5cyI6W3sia2V5IjpudWxsLCJobWFjX2tleSI6bnVsbCwidGltZSI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwiZWNfeCI6bnVsbCwiZWNfeSI6bnVsbCwiZWNfZCI6bnVsbCwicnNhX2tleSI6bnVsbCwicHVibGljX2tleSI6IiIsImNyZWF0aW9uX3RpbWUiOjB9LHsia2V5IjoiVyt5OGdHTjB3YkwySzlPeTVxTzdZWjBrY3czL0dGYjVjOEkwc3ZTTDJxTT0iLCJobWFjX2tleSI6IlAwU3I4dWEyWmRETVE3T3doeERqdWdFOXdCUkd0NkF5eitLeE8zeWdjOUk9IiwidGltZSI6IjIwMTctMTItMDhUMTE6NTA6MDguNjEzODM3LTA1OjAwIiwiZWNfeCI6bnVsbCwiZWNfeSI6bnVsbCwiZWNfZCI6bnVsbCwicnNhX2tleSI6bnVsbCwicHVibGljX2tleSI6IiIsImNyZWF0aW9uX3RpbWUiOjE1MTI3NTE4MDh9XX19Cg=="
  }
}

25. Восстановление ключа

Эта конечная точка восстанавливает резервную копию как именованный ключ. Это восстановит ключи конфигурации и все версии именованного ключа, а также ключи HMAC. Входные данные для этой конечной точки должны быть выходными данными конечной точки /backup.

Для безопасности, по умолчанию бэкенд откажется восстановить существующий ключ. Если вы хотите повторно использовать имя ключа, рекомендуется удалить ключ перед восстановлением. Хорошей практикой будет попытаться восстановить с использованием другого имени ключа в первую очередь, чтобы убедиться, что операция завершается успешно.
Метод Путь

POST

/transit/keys/:name/restore

25.1. Параметры

  • backup (string: <обязательный>) - данные резервной копии ключа для восстановления. Это должно быть выходное значение из конечной точки /backup.

  • name (string: <необязательный>) - если указано, это будет имя восстановленного ключа.

  • force (bool: false) - если установлено, принудит восстановление, даже если ключ с таким именем уже существует.

25.2. Пример тела запроса

{
    "backup": "eyJwb2xpY3kiOnsibmFtZSI6ImFlcyIsImtleXMiOnsiMSI6eyJrZXkiOiJXK3k4Z0dOMHdiTDJLOU95NXFPN1laMGtjdzMvR0ZiNWM4STBzdlNMMnFNPSIsImhtYWNfa2V5IjoiUDBTcjh1YTJaZERNUTdPd2h4RGp1Z0U5d0JSR3Q2QXl6K0t4TzN5Z2M5ST0iLCJ0aW1lIjoiMjAxNy0xMi0wOFQxMTo1MDowOC42MTM4MzctMDU6MDAiLCJlY194IjpudWxsLCJlY195IjpudWxsLCJlY19kIjpudWxsLCJyc2Ffa2V5IjpudWxsLCJwdWJsaWNfa2V5IjoiIiwiY3JlYXRpb25fdGltZSI6MTUxMjc1MTgwOH19LCJkZXJpdmVkIjpmYWxzZSwia2RmIjowLCJjb252ZXJnZW50X2VuY3J5cHRpb24iOmZhbHNlLCJleHBvcnRhYmxlIjpmYWxzZSwibWluX2RlY3J5cHRpb25fdmVyc2lvbiI6MSwibWluX2VuY3J5cHRpb25fdmVyc2lvbiI6MCwibGF0ZXN0X3ZlcnNpb24iOjEsImFyY2hpdmVfdmVyc2lvbiI6MSwiZGVsZXRpb25fYWxsb3dlZCI6ZmFsc2UsImNvbnZlcmdlbnRfdmVyc2lvbiI6MCwidHlwZSI6MCwiYmFja3VwX2luZm8iOnsidGltZSI6IjIwMTctMTItMDhUMTE6NTA6MjkuMjI4MTU3LTA1OjAwIiwidmVyc2lvbiI6MX0sInJlc3RvcmVfaW5mbyI6bnVsbH0sImFyY2hpdmVkX2tleXMiOnsia2V5cyI6W3sia2V5IjpudWxsLCJobWFjX2tleSI6bnVsbCwidGltZSI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwiZWNfeCI6bnVsbCwiZWNfeSI6bnVsbCwiZWNfZCI6bnVsbCwicnNhX2tleSI6bnVsbCwicHVibGljX2tleSI6IiIsImNyZWF0aW9uX3RpbWUiOjB9LHsia2V5IjoiVyt5OGdHTjB3YkwySzlPeTVxTzdZWjBrY3czL0dGYjVjOEkwc3ZTTDJxTT0iLCJobWFjX2tleSI6IlAwU3I4dWEyWmRETVE3T3doeERqdWdFOXdCUkd0NkF5eitLeE8zeWdjOUk9IiwidGltZSI6IjIwMTctMTItMDhUMTE6NTA6MDguNjEzODM3LTA1OjAwIiwiZWNfeCI6bnVsbCwiZWNfeSI6bnVsbCwiZWNfZCI6bnVsbCwicnNhX2tleSI6bnVsbCwicHVibGljX2tleSI6IiIsImNyZWF0aW9uX3RpbWUiOjE1MTI3NTE4MDh9XX19Cg=="
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/restore

26. Обрезка ключа

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

Метод Путь

POST

/transit/keys/:name/trim

26.1. Параметры

  • min_available_version (int: <обязательный>) - минимальная доступная версия для ключевого кольца. Все версии до этой версии будут навсегда удалены. Это значение не может быть меньше между min_decryption_version и min_encryption_version. Установка этого значения не разрешается, если либо min_encryption_version, либо min_decryption_version установлены в ноль.

Пример тела запроса:
{
  "min_available_version": 2
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key/trim

27. Конфигурация кэша

Эта конечная точка используется для настройки кэша движка Transit. Обратите внимание, что изменения конфигурации не будут применены до тех пор, пока плагин Transit не будет перезагружен, что можно сделать с помощью конечной точки /sys/plugins/reload/backend в конфигурации сервера StarVault.

Метод Путь

POST

/transit/cache-config

27.1. Параметры

  • size (int: 0) - указывает размер в терминах количества записей. Размер 0 означает неограниченный. Используется стратегия кэширования наименьших недавно использованных (LRU) для ненулевого размера кэша. Должно быть 0 (по умолчанию) или значение, большее или равное 10 (минимальный размер кэша).

Пример тела запроса:
{
  "size": 456
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/cache-config

28. Чтение конфигурации кэша Transit

Эта конечная точка получает конфигурации для кэша движка Transit.

Метод Путь

GET

/transit/cache-config
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/transit/cache-config
Пример ответа:
{
  "data": {
    "size": 0
  }
}

29. Подписание CSR

Эта конечная точка подписывает CSR с использованием ключа :name, обеспечивая сохранение ключевых материалов внутри Transit. Если CSR не предоставлено, он подписывает пустой CSR. В противном случае он подписывает предоставленный CSR, заменяя его ключевой материал на ключевой материал :name. Ключ в Transit должен быть ключом для подписи и не должен быть выводимым.

Метод Путь

POST

/transit/keys/:name/csr

29.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа для подписания CSR. Это указано как часть URL.

  • version (int, optional) - версия ключа для использования при подписании. Если версия установлена в latest или не установлена, текущий ключ будет возвращен.

  • csr (string, optional) - опциональный PEM-кодированный шаблон CSR, который будет использоваться в качестве основы для нового CSR, подписанного этим ключом. Если не указано, используется пустое CSR.

Пример тела запроса:
{
  "version": 3,
  "csr": "..."
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key/csr
Пример ответа:
{
  "data": {
    "name": "my-key",
    "type": "rsa-2048",
    "csr": "..."
  }
}

30. Установить цепочку сертификатов

Эта конечная точка устанавливает цепочку сертификатов для ключа :name, обеспечивая, что ключевые материалы остаются внутри Transit и сертификаты управляются в одном месте. Это также позволяет обновлять цепочки и их ротацию, так как она заменит любую существующую цепочку сертификатов.

Метод Путь

POST

/transit/keys/:name/set-certificate

30.1. Параметры

  • name (string: <обязательный>) - указывает имя ключа, чтобы импортировать цепочку сертификатов. Это указано как часть URL.

  • version (int, optional) - указывает версию ключа для импорта цепочки сертификатов. Если версия установлена в latest или не установлена, текущий ключ будет возвращен.

  • certificate_chain (string: <обязательный>) - PEM-кодированная цепочка сертификатов. Она должна сложиться из одного или нескольких объединенных PEM блоков и быть упорядоченной, начиная с сертификата конечного пользователя.

Пример тела запроса:
{
  "version": 3,
  "certificate_chain": "..."
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key/set-certificate
Пример ответа:
{
  "data": {
    "name": "my-key",
    "type": "rsa-2048",
    "certificate_chain": "..."
  }
}