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

/sys/rekey-recovery-key

Конечные точки /sys/rekey-recovery-key используются для смены ключей восстановления StarVault. Смена ключей применяется только к печатям, поддерживающим ключи восстановления.

1. Чтение прогресса смены ключа

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

Метод

Путь

GET

/sys/rekey-recovery-key/init
Пример запроса:
curl \
  http://127.0.0.1:8200/v1/sys/rekey-recovery-key/init
Пример ответа:
{
  "started": true,
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "t": 3,
  "n": 5,
  "progress": 1,
  "required": 3,
  "pgp_fingerprints": ["abcd1234"],
  "backup": true,
  "verification_required": false
}

Если запущена смена ключей, то n нужно ли генерировать новые общие ресурсы и t требуется ли пороговое значение для новых общих ресурсов. progress— количество ключей восстановления, предоставленных для этой смены ключей, которое required необходимо достичь для завершения. nonce Также отображается текущая операция смены ключей. Если для шифрования последних общих ресурсов используются ключи PGP, также отображаются отпечатки ключей и информация о том, будут ли резервные копии последних ключей создаваться на физическом носителе. — verification_required указывает, была ли включена верификация для этой операции.

2. Смена ключа

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

Метод

Путь

POST

/sys/rekey-recovery-key/init

2.1. Параметры

  • secret_shares (int: <required>) – указывает количество частей, на которые следует разделить ключ восстановления.

  • secret_threshold (int: <required>) – указывает количество акций, необходимое для восстановления ключа восстановления. Оно должно быть меньше или равно secret_shares.

  • pgp_keys (array<string>: nil) – задаёт массив открытых ключей PGP, используемых для шифрования выходных ключей восстановления. Порядок сохраняется. Ключи должны быть закодированы в формате base64 из исходного двоичного представления. Размер этого массива должен быть таким же, как и secret_shares.

  • backup (bool: false) – указывает, следует ли StarVault при использовании ключей, зашифрованных с помощью PGP, хранить резервную копию ключей в открытом виде на бэкенде физического хранилища core/unseal-keys-backup. Затем эти резервные копии можно извлечь и удалить через конечную точку sys/rekey-recovery-key/backup.

  • require_verification (bool: false) – включает функцию проверки. При включении проверки после успешной авторизации с текущими ключами распечатывания возвращаются новые ключи распечатывания, но ключ восстановления фактически не ротируется. Новые ключи должны быть предоставлены для авторизации фактической ротации ключа. Это гарантирует успешное сохранение новых ключей и защищает от риска их потери после ротации, но до того, как они будут сохранены. Это можно использовать как с pgp_keys, так и без него, и при использовании - позволяет гарантировать, что возвращенные ключи могут быть успешно расшифрованы перед фиксацией в новых частях, чего не обеспечивает функция резервного копирования.

Пример тела запроса:
{
  "secret_shares": 10,
  "secret_threshold": 5
}
Пример запроса:
curl \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/rekey-recovery-key/init

3. Отмена смены ключа

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

Проверка всё ещё является частью смены ключа. Если смена ключа отменяется во время процесса проверки, текущие ключи распечатывания остаются действительными.

Метод

Путь

DELETE

/sys/rekey-recovery-key/init
Пример запроса:
curl \
  --request DELETE \
  http://127.0.0.1:8200/v1/sys/rekey-recovery-key/init

4. Чтение резервного ключа

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

Метод

Путь

GET

/sys/rekey-recovery-key/backup
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  http://127.0.0.1:8200/v1/sys/rekey-recovery-key/backup
Пример ответа:
{
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "keys": {
    "abcd1234": "..."
  }
}

5. Удаление резервного ключа

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

Метод

Путь

DELETE

/sys/rekey-recovery-key/backup
Пример запроса:
curl \
  --header "X-Vault-Token" \
  --request DELETE \
  http://127.0.0.1:8200/v1/sys/rekey-recovery-key/backup

6. Отправка ключа

Эта конечная точка используется для ввода одной части ключа восстановления для выполнения смены ключа StarVault. Если достигнуто пороговое количество частей ключей восстановления, StarVault завершит смену ключа. В противном случае этот API необходимо вызывать несколько раз, пока не будет достигнуто это пороговое значение. Операция смены ключа должна предоставляться при каждом вызове.

После завершения операции будет возвращен ответ, подобный приведенному ниже примеру; в противном случае ответ будет таким же, как у GET метода sys/rekey-recovery-key/init, предоставляющего статус самой операции.

Если была запрошена проверка, успешное завершение этого потока немедленно переведет операцию в состояние проверки и предоставит одноразовый код для операции проверки.

Метод

Путь

POST

/sys/rekey-recovery-key/update

6.1. Параметры

  • key (string: <required>) – указывает одну часть ключа восстановления.

  • nonce (string: <required>) – указывает одноразовый номер операции смены ключа.

Пример тела запроса:
{
  "key": "AB32...",
  "nonce": "abcd1234..."
}
Пример запроса:
curl \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/rekey-recovery-key/update
Пример ответа:
{
  "complete": true,
  "keys": ["one", "two", "three"],
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "pgp_fingerprints": ["abcd1234"],
  "keys_base64": ["base64keyvalue"],
  "backup": true,
  "verification_required": true,
  "verification_nonce": "8b112c9e-2738-929d-bcc2-19aff249ff10"
}

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

7. Чтение хода проверки смены ключа

Данная конечная точка считывает конфигурацию и ход текущей попытки проверки смены ключа.

Метод

Путь

GET

/sys/rekey-recovery-key/verify
Пример запроса:
curl \
  http://127.0.0.1:8200/v1/sys/rekey-recovery-key/verify
Пример ответа:
{
  "nonce": "8b112c9e-2738-929d-bcc2-19aff249ff10",
  "t": 3,
  "n": 5,
  "progress": 1
}

n — общее количество сгенерированных частей и t пороговое значение, необходимое для прохождения проверки новыми частями. progress — количество новых ключей распечатывания, предоставленных для этой операции проверки. Также отображается значение nonce для текущей операции перезаписи ключей.

8. Отмена проверки смены ключа

Эта конечная точка отменяет любую текущую операцию проверки смены ключа. Это очищает весь достигнутый прогресс и сбрасывает одноразовый код. В отличие от операции DELETE для sys/rekey-recovery-key/init, это сбрасывает только текущую операцию проверки, а не всю попытку смены ключа. Возвращаемое значение такое же, как GET и с новым одноразовым кодом.

Метод

Путь

DELETE

/sys/rekey-recovery-key/verify
Пример запроса:
curl \
  --request DELETE \
  http://127.0.0.1:8200/v1/sys/rekey-recovery-key/verify
Пример ответа:
{
  "nonce": "5827bbc1-0110-5725-cc21-beddc129d942",
  "t": 3,
  "n": 5,
  "progress": 0
}

9. Отправка ключа подтверждения

Данная конечная точка используется для ввода одной новой части ключа для продолжения операции проверки смены ключа. Если достигнуто пороговое количество новых частей ключа, StarVault завершит смену ключа, выполнив фактическую ротацию ключа восстановления. В противном случае этот API необходимо вызывать несколько раз, пока не будет достигнуто это пороговое значение. Одноразовый код должен предоставляться при каждом вызове.

После завершения операции будет возвращен ответ, подобный приведенному ниже примеру; в противном случае ответ будет таким же, как у GET метода sys/rekey-recovery-key/verify, предоставляющего статус самой операции.

Метод

Путь

POST

/sys/rekey-recovery-key/verify

9.1. Параметры

  • key (string: <required>) – указывает одну часть ключа восстановления из нового набора частей.

  • nonce (string: <required>) – задает одноразовый номер операции проверки смены ключа.

Пример тела запроса:
{
  "key": "A58d...",
  "nonce": "5a27bbc1..."
}
Пример запроса:
curl \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/rekey-recovery-key/verify
Пример ответа:
{
  "nonce": "5827bbc1-0110-5725-cc21-beddc129d942",
  "complete": true
}