`/sys/generate-root`

Конечная точка /sys/generate-root используется для создания нового корневого ключа для StarVault.

1. Процесс генерации корневого ключа

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

Метод

Путь

GET

/sys/generate-root/attempt

Пример запроса:

curl \
  http://127.0.0.1:8200/v1/sys/generate-root/attempt

Пример ответа:

{
  "started": true,
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "progress": 1,
  "required": 3,
  "encoded_token": "",
  "pgp_fingerprint": "",
  "otp_length": 24,
  "complete": false
}

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

Если для шифрования конечного корневого токена используется ключ PGP, будет возвращен его отпечаток.

Если одноразовый пароль (OTP) используется для кодирования конечного корневого токена, он будет возвращен только один раз в ответе на запрос запуска.

Одноразовый пароль (OTP) представляет собой строку в кодировке base62 длиной otp_length. Необработанные байты (коды символов) токена будут подвергнуты операции XOR с этим значением, прежде чем будут возвращены в качестве ответа на последний ключ распечатывания, закодированный в формате base64.

2. Начало генерации корневого токена

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

Метод

Путь

POST

/sys/generate-root/attempt

2.1. Параметры

pgp_key (string: <optional>) – Задаёт открытый ключ PGP, закодированный в формате Base64. Необработанные байты токена будут зашифрованы этим значением перед возвратом поставщику окончательного распечатанного ключа.

Пример запроса:

curl \
  --request POST \
  http://127.0.0.1:8200/v1/sys/generate-root/attempt

Пример ответа:

{
  "started": true,
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "progress": 1,
  "required": 3,
  "encoded_token": "",
  "otp": "2vPFYG8gUSW9npwzyvxXMug0",
  "otp_length": 24,
  "complete": false
}

3. Отмена генерации корня

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

Метод

Путь

DELETE

/sys/generate-root/attempt

Пример запроса:

curl \
  --request DELETE \
  http://127.0.0.1:8200/v1/sys/generate-root/attempt

4. Предоставление общего ключа для генерации корневого токена

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

Метод

Путь

POST

/sys/generate-root/update

4.1. Параметры

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

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

{
  "key": "acbd1234",
  "nonce": "ad235"
}

Пример запроса:

curl \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/generate-root/update

Возвращается закодированный в формате JSON объект, указывающий одноразовый номер попытки, статус завершения и закодированный корневой токен, если попытка завершена.

Пример ответа:

{
  "started": true,
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "progress": 3,
  "required": 3,
  "pgp_fingerprint": "",
  "complete": true,
  "encoded_token": "FPzkNBvwNDeFh4SmGA8c+w=="
}