Движки секретов. TOTP (API)

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

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

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

Эта конечная точка создает или обновляет определение ключа.

Метод Путь

Метод	Путь
`POST`	`/totp/keys/:name`

POST

/totp/keys/:name

1.1. Параметры

name (string: <обязательный>) - указывает имя ключа, который нужно создать. Это указано как часть URL.
generate (bool: false) - указывает, должен ли ключ быть сгенерирован StarVault или передан из другого сервиса.
exported (bool: true) - указывает, будут ли возвращены QR-код и URL при генерации ключа. Используется только если generate равно true.
key_size (int: 20) - указывает размер в байтах сгенерированного ключа StarVault. Используется только если generate равно true.
url (string: "") - указывает строку URL ключа TOTP, которая может использоваться для настройки ключа. Используется только если generate равно false.
key (string: <обязательный - если generate равно false и url пустой>) - указывает корневой ключ, используемый для генерации TOTP кода. Используется только если generate равно false.
issuer (string: "" <обязательный - если generate равно true>) - указывает имя организации, выдавшей ключ.
account_name (string: "" <обязательный - если generate равно true>) - указывает имя учетной записи, связанной с ключом.
period (int или строка формата длительности: 30) - указывает длину времени в секундах, используемую для генерации счетчика для вычисления TOTP кода.
algorithm (string: "SHA1") - указывает хеширующий алгоритм, используемый для генерации TOTP кода. Опции включают "SHA1", "SHA256" и "SHA512".
digits (int: 6) - указывает количество цифр в сгенерированном TOTP коде. Это значение может быть установлено на 6 или 8.
skew (int: 1) - указывает количество промежутков задержки, разрешенных при проверке TOTP кода. Это значение может быть либо 0, либо 1. Используется только если generate равно true.
qr_size (int: 200) - указывает размер в пикселях квадратного QR-кода при генерации нового ключа. Используется только если generate равно true и exported равно true. Если это значение равно 0, QR-код не будет возвращен.

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

{
  "url": "otpauth://totp/Google:test@gmail.com?secret=Y64VEVMBTSXCYIWRSHRNDZW62MPGVU2G&issuer=Google"
}

1.3. Пример запроса

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/totp/keys/my-key

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

{
  "generate": true,
  "issuer": "Google",
  "account_name": "test@gmail.com"
}

1.5. Пример запроса

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/totp/keys/my-key

1.6. Пример ответа

{
  "data": {
    "barcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGXklEQVR4nOyd4Y4iOQyEmRPv/8p7upX6BJm4XbbDbK30fT9GAtJJhpLjdhw3z1+/HmDEP396AvDO878/X1+9i1frWvu5Po/6Xz+P2kft1nFVa1f7z+YdjT/5PrEQMxDEDAQx4/n6orsGr6z9ZP1mviMbP/MBav/R6/U61Ud0vk8sxAwEMQNBzHju3lTvv6P2ajwS9Ve9zz+9pkfjRp+r/SjzwULMQBAzEMSMrQ/pUo0bouun7dW9LXVvrBq/TMBCzEAQMxDEjKM+JFqT17W4mu9Y+49eq/OL3r/GVX3CJ7KtWIgZCGIGgpix9SHTtXGa4476qfoa1adVc+HV/6/yfWIhZiCIGQhixpsP6Z4nulD3lqavV7q+Yvo6G7/zfWIhZiCIGQhixteJ/Rh1Da3e71d9RjRul2ocdeK7xELMQBAzEMSM3z6ku6dTrdOo1l9M6y5O7clVx5n4SCzEDAQxA0HMuN3L+qlavqj9itpePY+VtVdrHqfzeQULMQNBzEAQM97ikAv1vr/brltTeCp/svarcjLe2F1PnbohCGIGgphRqjG8mJ6PmtYMVnP363Vqv6d8qZrzf2AhfiCIGQhixm0c8n+jQ8+7+jZ4cY3PrlfHO/1Ml+45st18sRAzEMQMBDHjdxyixgPqs0lWsvvwqH00zrSO41R80p3XXXssxAwEMQNBzJCeuaieo6pedzGtb1/76fqgLH6ofg+dZ65gIWYgiBkIYsbbs9/V+/EVde1V+62eh1I/r/qIrs+Ixo2uYy/LGAQxA0HMeNvLilDX1OraXc2jVNtPzxJXr6v+HzuwEDMQxAwEMWNbp95d21WmzzBR6066e07dPMxPgoWYgSBmbOvUV7q577VdOIliXqLr87p7Tere2YnrsRAzEMQMBDFj+zuGar3Gp+rNp3kUtR5lmj/Jxo/GvZsvFmIGgpiBIGbcPi/rW+MPPaeqOs407xL1E1E9lzWpg8FCzEAQMxDEDOk3qC66a7f6fsSn1uz18+o8P+GzsBAzEMQMBDFjm1Ov7L3s3p+2/6lcfoa6ZxaNm50DWyEOMQRBzEAQM7Zne6PX3XilW5M3zbd0c/3ZHpvqY6P+7j7HQsxAEDMQxIxRPqRaT6Kuzemkh7WJ3RrJbJxq7eOuPyzEDAQxA0HMKJ3t/XbxobW/Gmdka/PpPMxPgoWYgSBmIIgZ0m9QrXTP1mb9Ru2y+/hsD2xaM9jN5UfjEIf8RSCIGQhiRus3qLp7ONU6jK4vynxMdn10XdY+m4/SHxZiBoKYgSBm3MYhGdl9/qkzvN18ilpDqF6nxiPVGs3Xz7EQMxDEDAQx4/ZcVoR6fqobZ6h7Vtm81TVejZdWuvHNXXssxAwEMQNBzHju3pyujdO68Ky9Wm+h9qPGJVG/6nyU+WIhZiCIGQhixtaHdFF9hlqLeOrcVPcMQDeOmtTNYyFmIIgZCGLGUR/SPQs73QuL5tGtiVznlc1X/T8iXtthIWYgiBkIYsbWh3T3nNS1dXqe6tReW8S0Hr1b5/LAQvxAEDMQxIw3H9I9nzU9R6XGHdn41dx4d4+rGp9En7OX9ReAIGYgiBlff6IWG2KwEDP+DQAA//+TDHXGhqE4+AAAAABJRU5ErkJggg==",
    "url": "otpauth://totp/Google:test@gmail.com?algorithm=SHA1&digits=6&issuer=Google&period=30&secret=HTXT7KJFVNAJUPYWQRWMNVQE5AF5YZI2"
  }
}

Если возвращается QR-код, он состоит из Bytes PNG, отформатированных в Base64. Вы можете встроить его на веб-страницу, включая строку в Base64 в тег img с префиксом data:image/png;base64

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUh.." />

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

Эта конечная точка запрашивает определение ключа.

Метод Путь

Метод	Путь
`GET`	`/totp/keys/:name`

GET

/totp/keys/:name

2.1. Параметры

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

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

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/totp/keys/my-key

2.2. Пример ответа

{
  "data": {
    "account_name": "test@gmail.com",
    "algorithm": "SHA1",
    "digits": 6,
    "issuer": "Google",
    "period": 30
  }
}

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

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

Метод Путь

Метод	Путь
`LIST`	`/totp/keys`

LIST

/totp/keys

3.1. Параметры

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

3.2. Пример запроса

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/totp/keys

3.3. Пример ответа

{
  "auth": null,
  "data": {
    "keys": ["my-key"]
  },
  "lease_duration": 0,
  "lease_id": "",
  "renewable": false
}

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

Эта конечная точка удаляет определение ключа.

Метод Путь

Метод	Путь
`DELETE`	`/totp/keys/:name`

DELETE

/totp/keys/:name

4.1. Параметры

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

4.2. Пример запроса

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/totp/keys/my-key

5. Генерация кода

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

Метод Путь

Метод	Путь
`GET`	`/totp/code/:name`

GET

/totp/code/:name

5.1. Параметры

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

5.2. Пример запроса

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/totp/code/my-key

5.3. Пример ответа

{
  "data": {
    "code": "810920"
  }
}

6. Проверка кода

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

Метод Путь

Метод	Путь
`POST`	`/totp/code/:name`

POST

/totp/code/:name

6.1. Параметры

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

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

{
  "code": "123802"
}

6.3. Пример запроса

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/totp/code/my-key

6.4. Пример ответа

{
  "data": {
    "valid": true
  }
}