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

/sys/rekey

Конечные точки /sys/rekey используются для повторной установки ключей распечатывания для StarVault.

На устройствах с печатями, поддерживающих сохранённые ключи (например, HSM PKCS11), можно предоставить общие ключи восстановления для перекодировки корневого ключа, поскольку доступные ключи раскодировки отсутствуют. Параметры секретных общих ключей, порога секретности и сохранённых общих ключей должны быть установлены равными 1. После успешной перекодировки разделённые общие ключи раскодировки не возвращаются.

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

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

Метод

Путь

GET

/sys/rekey/init
Пример запроса:
curl \
  http://127.0.0.1:8200/v1/sys/rekey/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/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/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/init

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

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

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

Метод

Путь

DELETE

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

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

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

Метод

Путь

GET

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

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

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

Метод

Путь

DELETE

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

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

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

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

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

Метод

Путь

POST

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

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

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

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

Метод

Путь

DELETE

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

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

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

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

Метод

Путь

POST

/sys/rekey/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/verify
Пример ответа:
{
  "nonce": "5827bbc1-0110-5725-cc21-beddc129d942",
  "complete": true
}