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

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

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

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

1. Содержание

2. Уведомление о новой функциональности с несколькими удостоверяющими центрами

StarVault позволяет одному монтированию движка секретов SSH иметь несколько сертификатов Центра Сертификации (CA), называемых "удостоверяющими центрами". Эта функция предназначена специально для упрощения ротации CA. Стандартный удостоверяющий центр должен быть явно создан и настроен для монтирования. После настройки этот стандартный удостоверяющий центр будет использоваться для всех операций, когда в процессе создания роли не упоминается конкретный удостоверяющий центр. Стандартный удостоверяющий центр может быть изменен в любое время, либо путем подачи/создания нового удостоверяющего центра, либо обновления его через конечную точку конфигурации.

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

3. Управление информацией об авторитете

3.1. Список ролей

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

Метод Путь

LIST

/ssh/roles

3.1.1. Параметры

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

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

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

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

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

{
  "auth": null,
  "data": {
    "keys": ["dev", "prod"],
    "key_info": {
      "dev": {
        "key_type": "ca",
        "issuer_ref": "default"
      }
    }
  },
  "lease_duration": 2764800,
  "lease_id": "",
  "renewable": false
}

3.2. Список ролей по IP

Эта конечная точка перечисляет все роли, с которыми связан данный IP-адрес.

Метод Путь

POST

/ssh/lookup

3.2.1. Параметры

  • ip (string: <обязательный>) - указывает IP-адрес удаленного хоста.

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

{
  "ip": "1.2.3.4"
}

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/lookup

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

Массив ролей в виде структуры секрета.

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "roles": [
      "fe6f61b7-7e4a-46a6-b2c8-0d530b8513df",
      "6d6411fd-f622-ea0a-7e2c-989a745cbbb2"
    ]
  },
  "warnings": null,
  "auth": null
}

3.3. Создание/Обновление роли

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

Метод Путь

POST

/ssh/roles/:name

3.3.1. Параметры

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

  • default_user (string: "") - указывает имя пользователя по умолчанию, для которого будет создана учетная запись. Когда конечная точка creds/ используется без имени пользователя, это значение будет использоваться как имя пользователя по умолчанию. Рекомендуется создавать отдельные роли для каждого имени пользователя, чтобы обеспечить абсолютную изоляцию между именами пользователей. Это требуется для ролей типа OTP.

    Когда default_user_template установлено в true, это поле может содержать шаблон идентичности с любым префиксом или суффиксом, например ssh-{{identity.entity.id}}-user.

    Для ролей типа CA, если вы хотите, чтобы это было действительным принцепом, оно также должно находиться в allowed_users.

  • default_user_template (bool: false) - если установлено, default_users может быть указано с использованием значений шаблона идентичности. Также разрешены нес шаблонные пользователи.

  • cidr_list (string: "") - указывает запятую-разделенный список CIDR-блоков, для которых роле разрешено выдавать сертификаты. Возможно, один и тот же набор CIDR блоков будет частью нескольких ролей. Это является обязательным параметром, если роль не зарегистрирована под конечной точкой /config/zeroaddress.

    Не применимо для типов CA.

  • exclude_cidr_list (string: "") - указывает запятую-разделенный список CIDR блоков. IP-адреса, принадлежащие этим блокам, не принимаются ролью. Это особенно полезно, когда большие CIDR-блоки используются ролью и определенные части нужно исключить.

    Не применимо для типов CA.

  • port (int: 22) - указывает номер порта для SSH-соединения. Номер порта не играет никакой роли в генерации OTP. Для типа секретов otp этот параметр просто информирует клиента о номере порта, который нужно использовать. Номер порта будет возвращен клиенту StarVault вместе с OTP.

  • key_type (string: <обязательный>) - указывает тип учетных данных, генерируемых этой ролью. Это может быть либо otp, либо ca.

  • allowed_users (string: "") - если эта опция не указана или равна *, клиент может запросить учетные данные для любого действительного пользователя на удаленном хосте, включая пользователя-администратора. Чтобы разрешить только явный список пользователей, установите этот параметр с использованием запятой-разделенного списка имен пользователей для принуждения. Когда этот параметр установлен, учетные записи создаются только для default_user и перечисленных имен пользователей. Установка этой опции позволит всем пользователям, имеющим доступ к этой роли, получать учетные данные для всех других имен пользователей в этом списке. Когда allowed_users_template установлено в true, это поле может содержать шаблон идентичности с любым префиксом или суффиксом, например ssh-{{identity.entity.id}}-user. Используйте с осторожностью. Обратите внимание: если типом является ca, пустой список не позволяет ни одному пользователю; вместо этого нужно использовать *, чтобы включить это поведение.

  • allowed_users_template (bool: false) - если установлено, allowed_users можно указать с использованием политик шаблонизации идентичности. Также разрешены нес шаблонные пользователи.

  • allowed_domains (string: "") - запятая-разделенный список доменов, для которых клиент может запросить сертификат хоста. Если эта опция явно установлена в "*", возможности создания учетных данных будут доступны для любого домена. Также смотрите allow_bare_domains и allow_subdomains.

  • allowed_domains_template (bool: false) - если установлено, allowed_domains может быть указано с использованием политик шаблонизации идентичности. Нешаблонированные домены также разрешены.

  • ttl (string: "") - указывает значение времени жизни, предоставленное в виде строки длительности с суффиксом времени. Часы - наибольший суффикс. Если не установлено, используется системное значение по умолчанию или значение max_ttl, что короче.

  • max_ttl (string: "") - указывает максимальное значение времени жизни, предоставленное в виде строки длительности с суффиксом времени. Часы - наибольший суффикс. Если не установлено, по умолчанию используется максимальный TTL аренды системы.

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

  • allowed_extensions (string: "") - указывает запятую-разделенный список расширений, которые сертификаты могут иметь при подписании. Чтобы разрешить пользователю указывать любое расширение, установите это в "*". Если не установлено, пользователям не будет разрешено указывать расширения и они получат расширения, указанные в default_extensions. Для списка расширений смотрите раздел AUTHORIZED_KEYS FILE FORMAT справочного руководства sshd. Вы должны добавить префикс permit- перед именем расширения, чтобы разрешить его.

  • default_critical_options (map<string|string>: "") - указывает карту критических опций, которые сертификаты должны иметь, если никаких не предоставлено при подписании. Это поле принимает пары ключ-значение в формате JSON. Обратите внимание, что это не ограничивается allowed_critical_options. По умолчанию отсутствуют.

  • default_extensions (map<string|string>: "") - указывает карту расширений, которые сертификаты должны иметь, если никаких не предоставлено при подписании. Это поле принимает пары ключ-значение в формате JSON. Обратите внимание, что это не ограничивается allowed_extensions. По умолчанию отсутствуют.

  • default_extensions_template (bool: false) - Если установлено, default_extensions может быть указано с использованием политик шаблонизации идентичности. Нешаблонные расширения также разрешены.

  • allow_user_certificates (bool: false) - указывает, разрешены ли сертификаты, подписанные для использования в качестве «пользователя».

  • allow_host_certificates (bool: false) - указывает, разрешены ли сертификаты, подписанные для использования в качестве «хоста».

  • allow_bare_domains (bool: false) - указывает, разрешено ли хост-сертификатам, которые запрашиваются, использовать базовые домены, указанные в allowed_domains, например, «example.com». Это отдельная опция, поскольку в некоторых случаях это может быть расценено как угроза безопасности.

  • allow_subdomains (bool: false) - указывает, разрешены ли хост-сертификаты, которые запрашиваются, могут быть поддоменами тех, что указаны в allowed_domains, например, если «example.com» является частью allowed_domains, это позволяет «foo.example.com».

  • allow_user_key_ids (bool: false) - указывает, могут ли пользователи переопределять идентификатор ключа для подписанного сертификата с помощью поля «key_id». Если значение false, идентификатор ключа всегда будет равен имени дисплея токена. Идентификатор ключа регистрируется сервером SSH и может быть полезен для аудита.

  • key_id_format (string: "") - Когда предоставлено, это значение указывает на пользовательский формат для идентификатора ключа подписанного сертификата. Доступны следующие переменные для использования: {{token_display_name}} - имя дисплея токена, использованного для запроса. {{role_name}} - имя роли, подписывающей запрос. {{public_key_hash}} - SHA256 сумма контрольной суммы публичного ключа, который подписывается. Например, "custom-keyid-{{token_display_name}}".

  • allowed_user_key_lengths (map<string|(int|[]int|string)>: "") - указывает на карту типов ssh ключей и их ожидаемых размеров, которые могут быть подписаны типом CA. Чтобы указать несколько размеров, используйте запятую-разделенный список или массив разрешенных ширин ключей. Мы поддерживаем как идентификаторы ключей в стиле OpenSSH, так и короткие имена (rsa, ecdsa, dsa, или ed25519) в качестве ключей. Например, действительной политикой для разрешения распространенных RSA и ECDSA размеров ключей может быть:

    {
  "rsa": [2048, 3072, 4096],
  "ec": 256,
  "ecdsa-sha2-nistp521": 0
}

    Обратите внимание, что когда идентификатор алгоритма уникально указывает на длину ключа (например, с ecdsa-sha2-nistp256 или ed25519), значение длины игнорируется (и может быть равно нулю).

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

  • algorithm_signer (string: "default") - алгоритм для подписания ключей. Допустимыезначения: ssh-rsa, rsa-sha2-256, rsa-sha2-512, или default. Это значение также может быть оставлено пустым для использования алгоритма по умолчанию подписчика, и его нужно оставить пустым или указать default для типов ключей CA, отличных от RSA.

Значение default может изменяться со временем по мере обнаружения уязвимостей в алгоритмах. Текущее значение для RSA ключей соответствует rsa-sha2-256.

Значение algorithm_signer ssh-rsa использует хеш алгоритм SHA-1. Этот алгоритм считается небезопасным и не поддерживается текущими версиями OpenSSH. В результате StarVault установил новый стандарт rsa-sha2-256 для RSA ключей CA. Настоятельно рекомендовать всем пользователям перейти на rsa-sha2-256 или default, если роль была создана с явным параметром algorithm_signer=rsa-sha или была мигрирована к такому.

  • not_before_duration (duration: "30s") - указывает продолжительность, на которую нужно отступить для свойства ValidAfter. Использует строки формата продолжительности.

  • allow_empty_principals (bool: false) - если установлено в true, сертификаты для хоста и пользователя могут выдаваться без действительных принципалов. Для сертификатов хоста это означает, что любой домен, которым хост заявляет, будет проверен клиентом, который подключается. Для сертификатов пользователя, когда CA сертификат размещается в файле AuthorizedKeys пользователя, любой принципал на этом сертификате будет разрешен для подключения. Когда allowed_users или allowed_domains установлено в * (соответствующим роли/типу сертификата), allow_empty_principals=false все равно допускает выдачу.

  • issuer_ref (string: "default") - указывает ссылку на удостоверяющий центр, которая будет использована для подписания запросов. Если не установлено, будет использован стандартный удостоверяющий центр. Это поле применимо только к ролям типа CA.

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

{
  "key_type": "otp"
}

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/roles/my-role

3.4. Чтение роли

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

Метод Путь

GET

/ssh/roles/:name

3.4.1. Параметры

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

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

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/ssh/roles/my-role

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

Для роли OTP:

{
  "cidr_list": "x.x.x.x/y",
  "default_user": "username",
  "key_type": "otp",
  "port": 22
}

Для роли CA:

{
  "allow_bare_domains": false,
  "allow_host_certificates": true,
  "allow_subdomains": false,
  "allow_user_key_ids": false,
  "allow_user_certificates": true,
  "allowed_critical_options": "",
  "allowed_extensions": "",
  "default_critical_options": {},
  "default_extensions": {},
  "issuer_ref": "default",
  "max_ttl": "768h",
  "ttl": "4h"
}

3.5. Удаление роли

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

Метод Путь

DELETE

/ssh/roles/:name

3.5.1. Параметры

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

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/ssh/roles/my-role

3.6. Список ролей Zero-Address

Эта конечная точка возвращает список настроенных ролей zero-address.

Метод Путь

GET

/ssh/config/zeroaddress

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

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/ssh/config/zeroaddress

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

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "roles": ["otp_key_role"]
  },
  "warnings": null,
  "auth": null
}

3.7. Настроить роли Zero-Address

Эта конечная точка настраивает роли zero-address.

Метод Путь

POST

/ssh/config/zeroaddress

3.7.1. Параметры

  • roles (string: <обязательный>) - указывает строку, содержащую запятую-разделенный список имен ролей, для которых разрешены учетные данные для любого IP-адреса. CIDR блоки, ранее зарегистрированные под этими ролями, будут проигнорированы.

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

{
  "roles": ["otp_key_role"]
}

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/config/zeroaddress

3.8. Удалить роли Zero-Address

Эта конечная точка удаляет конфигурацию ролей zero-address.

Метод Путь

DELETE

/ssh/config/zeroaddress

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/ssh/config/zeroaddress

3.9. Генерация SSH учетных данных

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

Метод Путь

POST

/ssh/creds/:name

3.9.1. Параметры

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

  • username (string: "") - указывает имя пользователя на удаленном хосте;

  • ip (string: <обязательный>) - указывает IP удаленного хоста.

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

{
  "ip": "1.2.3.4"
}

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/creds/my-role

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

Для роли OTP:

{
  "lease_id": "sshs/creds/c3c2e60c-5a48-415a-9d5a-a41e0e6cdec5/3ee6ad28-383f-d482-2427-70498eba4d96",
  "renewable": false,
  "lease_duration": 2764800,
  "data": {
    "ip": "127.0.0.1",
    "key": "6d6411fd-f622-ea0a-7e2c-989a745cbbb2",
    "key_type": "otp",
    "port": 22,
    "username": "rajanadar"
  },
  "warnings": null,
  "auth": null
}

3.10. Чтение конфигурации удостоверяющих центров

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

Метод Путь

GET

/ssh/config/issuers

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

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/ssh/config/issuers

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

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "default": "a38751e4-6cd1-f1b4-10ac-61eb2fcd3caf"
  },
  "warnings": null
}

3.11. Установка конфигурации удостоверяющих центров

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

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

Метод Путь

POST

/ssh/config/issuers

3.11.1. Параметры

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

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

{
  "default": "issuer-1"
}

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/config/issuers

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

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "default": "a38751e4-6cd1-f1b4-10ac-61eb2fcd3caf"
  },
  "warnings": null
}

3.12. Упорядочение ключей хоста

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

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

DELETE

/ssh/tidy/dynamic-keys

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/ssh/tidy/dynamic-keys

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

{
  "request_id": "",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "message": "Removed 15 of 15 host keys."
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

4. Управление удостоверяющими центрами

4.1. Список удостоверяющих центров

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

Метод Путь

LIST

/ssh/issuers

4.1.1. Параметры

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

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

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

$ curl \
    --request LIST \
    http://127.0.0.1:8200/v1/ssh/issuers

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

{
  "data": {
    "key_info": {
      "1ae8ce9d-2f70-0761-a465-8c9840a247a2": {
        "issuer_name": "issuer-1",
        "is_default": false,
        "public_key": "ssh-rsa AAAAHHNzaC1y...\n"
      },
      "3dc79a5a-7a6c-70e2-1123-94b88557ba12": {
        "issuer_name": "issuer-2",
        "is_default": false,
        "public_key": "ssh-rsa AAAAHHNzaC1y...\n"
      }
    },
    "keys": [
      "1ae8ce9d-2f70-0761-a465-8c9840a247a2",
      "3dc79a5a-7a6c-70e2-1123-94b88557ba12"
    ]
  }
}

4.2. Отправить информацию CA

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

Метод Путь Content-Type

POST

/ssh/config/ca

200 application/json

4.2.1. Параметры

  • private_key (string: "") - указывает закрытую часть ключа SSH CA; требуется, если generate_signing_key установлено в false.

  • public_key (string: "") - указывает публичную часть ключа SSH CA; требуется, если generate_signing_key установлено в false.

  • generate_signing_key (bool: true) - указывает, должен ли StarVault генерировать пару подписывающих ключей внутренне. Если true, создается пара RSA ключей, а сгенерированный публичный ключ возвращается, чтобы вы могли добавить его в свою конфигурацию. Если false, то вы должны предоставить private_key и public_key, которые могут быть любого допустимого типа подписывающего ключа.

  • key_type (string: ssh-rsa) - указывает желаемый тип ключа для сгенерированного ключа SSH CA, когда generate_signing_key установлено в true. Допустимые значения - идентификаторы типов ключей OpenSSH (ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521 или ssh-ed25519) или алгоритм (rsa, ec или ed25519).

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

  • key_bits (int: 0) - указывает желаемое количество бит для сгенерированного ключа SSH CA, когда generate_signing_key установлено в true. Это используется только для ключей переменной длины (таких как ssh-rsa, где значение key_bits указывает размер создаваемой пары RSA ключей; при значении по умолчанию 0 получаем 4096-битный ключ) или когда в key_type указан алгоритм ec (где значение key_bits определяет, какая NIST P-кривая будет использована; 256, 384 или 521, при значении по умолчанию 0, получаем ключ NIST P-256).

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

{
  "generate_signing_key": true
}

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/config/ca

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

Независимо от того, сгенерирован ли ключевой материал, когда generate_signing_key равно true, или отправлен, успешный ответ будет иметь статус 200 и формат тела, подобный следующему:

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "issuer_id": "a38751e4-6cd1-f1b4-10ac-61eb2fcd3caf",
    "issuer_name": "issuer-1",
    "public_key": "ssh-rsa AAAAHHNzaC1y...\n"
  },
  "warnings": null
}

4.3. Отправить информацию об удостоверяющем центре с необязательным именем

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

Установив параметр set_default в true, ссылка default будет обновлена на новый удостоверяющий центр, перезаписывая любую предыдущую конфигурацию стандартного удостоверяющего центра. При отправке первого удостоверяющего центра ссылка default будет установлена на него независимо от этого параметра.

Метод Путь Content-Type

POST

/ssh/issuers/import/:issuer_name

200 application/json

4.3.1. Параметры

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

  • private_key (string: "") - указывает закрытую часть ключа SSH CA; требуется, если generate_signing_key установлено в false.

  • public_key (string: "") - указывает публичную часть ключа SSH CA; требуется, если generate_signing_key установлено в false.

  • generate_signing_key (bool: true) - указывает, должен ли StarVault генерировать пару подписывающих ключей внутренне. Если true, создается пара RSA ключей, и сгенерированный публичный ключ возвращается, чтобы вы могли добавить его в свою конфигурацию. Если false, тогда вы должны предоставить private_key и public_key, которые могут быть любого допустимого типа подписывающего ключа.

  • key_type (string: ssh-rsa) - указывает желаемый тип ключа для сгенерированного ключа SSH CA, когда generate_signing_key установлено в true. Допустимые значения - идентификаторы типов ключей OpenSSH (ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521 или ssh-ed25519) или алгоритм (rsa, ec или ed25519).

  • set_default (bool: false) - указывает, должна ли отправленная или сгенерированная информация CA использоваться в качестве стандартного удостоверяющего центра. Если true, это станет стандартным удостоверяющим центром для выполнения операций, когда любая роль ссылается на него. Только один удостоверяющий центр может быть стандартным, и, если он уже установлен, он будет перезаписан.

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

  • key_bits (int: 0) - указывает желаемое количество бит для сгенерированного SSH CA ключа. Когда generate_signing_key установлено в true. Используется только для ключей переменной длины (таких как ssh-rsa, где значение key_bits указывает размер создаваемой пары RSA ключей; при значении по умолчанию 0 получаем 4096-битный ключ) или когда в key_type указан алгоритм ec (где значение key_bits определяет, какую NIST P-кривую использовать; 256, 384 или 521, при значении по умолчанию 0 получаем ключ NIST P-256).

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

{
  "generate_signing_key": true
}

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/issuers/import/issuer-1

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

Независимо от того, сгенерирован ли ключевой материал, когда generate_signing_key равно true, или отправлен, успешный ответ будет иметь статус 200 и формат тела, подобный следующему:

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "issuer_id": "a38751e4-6cd1-f1b4-10ac-61eb2fcd3caf",
    "issuer_name": "issuer-1",
    "public_key": "ssh-rsa AAAAHHNzaC1y...\n"
  },
  "warnings": null
}

4.4. Чтение удостоверяющего центра

Эта конечная точка позволяет оператору получить информацию об одном удостоверяющем центре по его ссылке, включая внутреннюю информацию, которая не раскрыта на неаутентифицированной конечной точке ssh/issuer/:issuer_ref/public_key. Эта информация включает идентификатор удостоверяющего центра, опциональное имя и информацию о том, установлен ли удостоверяющий центр в текущий момент как default.

Метод Путь

GET

/ssh/issuer/:issuer_ref

4.4.1. Параметры

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

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

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/ssh/issuer/default

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

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "issuer_id": "a38751e4-6cd1-f1b4-10ac-61eb2fcd3caf",
    "issuer_name": "issuer-1",
    "public_key": "ssh-rsa AAAAHHNzaC1y...\n"
  },
  "warnings": null
}

4.5. Чтение публичного ключа удостоверяющего центра (неаутентифицированно)

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

Это конечная точка с сырьевым ответом без кодирования в JSON; используйте starvault read -format=raw или инструмент внешнего вызова (например, curl), чтобы получить это значение.
Метод Путь Content-Type

GET

/ssh/issuer/:issuer_ref/public_key

200 text/plain

4.5.1. Параметры

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

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

$ curl http://127.0.0.1:8200/v1/ssh/issuer/issuer-1/public_key

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

ssh-rsa AAAAHHNzaC1y...

4.6. Чтение публичного ключа (аутентифицированно)

Эта конечная точка считывает настроенный/сгенерированный публичный ключ для стандартного удостоверяющего центра (CA).

Метод Путь

GET

/ssh/config/ca

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

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/ssh/config/ca

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

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "issuer_id": "a38751e4-6cd1-f1b4-10ac-61eb2fcd3caf",
    "issuer_name": "issuer-name",
    "public_key": "ssh-rsa AAAAHHNzaC1y...\n"
  },
  "warnings": null
}

4.7. Чтение публичного ключа (неаутентифицированно)

Эта конечная точка возвращает настроенный/сгенерированный публичный ключ для стандартного удостоверяющего центра (CA). Это неаутентифицированная конечная точка.

Это конечная точка с сырьевым ответом без кодирования в JSON; используйте starvault read -format=raw или инструмент внешнего вызова (например, curl), чтобы получить это значение.
Метод Путь Content-Type

GET

/ssh/public_key

200 text/plain

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

$ curl http://127.0.0.1:8200/v1/ssh/public_key

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

ssh-rsa AAAAHHNzaC1y...

4.8. Обновление удостоверяющего центра

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

Метод Путь

POST/PATCH

/ssh/issuer/:issuer_ref

4.8.1. Параметры

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

  • issuer_name (string: "") - указывает имя для указанного удостоверяющего центра. Имя должно быть уникальным среди всех удостоверяющих центров и не может быть зарезервированным значением default.

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

{
  "issuer_name": "issuer-2"
}

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/issuer/default

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

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "issuer_id": "a38751e4-6cd1-f1b4-10ac-61eb2fcd3caf",
    "issuer_name": "issuer-1",
    "public_key": "ssh-rsa AAAAHHNzaC1y...\n"
  },
  "warnings": null
}

4.9. Удаление информации CA

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

Метод Путь

DELETE

/ssh/config/ca

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/ssh/config/ca

4.10. Удаление удостоверяющего центра

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

Метод Путь

DELETE

/ssh/issuer/:issuer_ref

4.10.1. Параметры

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

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/ssh/issuer/issuer-1

5. Операции удостоверяющего центра

5.1. Подписание SSH ключа

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

Это похоже на конечную точку /ssh/issue/:name. Вместо выдачи новых SSH учетных данных, это возвращает сертификат для данного публичного SSH ключа.

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

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

Выданный сертификат возвращается, но не хранится StarVault. Если вы не сохраните его из ответа, выполните его снова, повторив этот запрос.
Метод Путь

POST

/ssh/sign/:name

5.1.1. Параметры

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

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

  • ttl (string: "") - указывает запрашиваемую продолжительность жизни. Не может быть больше, чем значение max_ttl роли. Если не предоставлено, будет используется значение ttl роли. Обратите внимание, что значения роли по умолчанию соответствуют системным значениям, если они не установлены явно.

  • valid_principals (string: "") - указывает допустимые принципы, либо имена пользователей, либо имена хостов, для которых сертификат должен быть подписан.

  • cert_type (string: "user") - указывает тип сертификата, который должен быть создан; либо "пользователь", либо "хост".

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

  • critical_options (map<string|string>: "") - указывает карту критических опций, для которых сертификат должен быть подписан. По умолчанию отсутствуют.

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

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

{
  "public_key": "ssh-rsa ..."
}

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

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

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

{
  "lease_id": "ssh/sign/example/097bf207-96dd-0041-0e83-b23bd1923993",
  "renewable": false,
  "lease_duration": 21600,
  "data": {
    "issuer_id": "a38751e4-6cd1-f1b4-10ac-61eb2fcd3caf",
    "serial_number": "f65ed2fd21443d5c",
    "signed_key": "ssh-rsa-cert-v01@openssh.com AAAAHHN...\n"
  },
  "auth": null
}

5.2. Генерация сертификата и ключа

Эта конечная точка выдает новый набор SSH учетных данных (закрытый ключ и сертификат).

Она похожа на конечную точку /ssh/sign/:name: вместо подписания существующего публичного SSH ключа она генерирует и выдает новые учетные данные SSH (ключ и сертификат).

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

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

Выданные учетные данные возвращаются, но не хранятся StarVault. Если вы не сохраните их из ответа, выдайте новые учетные данные, снова повторив этот запрос.
Метод Путь

POST

/ssh/issue/:name

5.2.1. Параметры

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

  • key_type (string: "rsa") - указывает желаемый тип ключа; должен быть rsa, ed25519 или ec.

  • key_bits (int: 0) - указывает количество бит, которые следует использовать для сгенерированных ключей. Допустимые значения: 0 (универсальное значение по умолчанию); с key_type=rsa, допустимые значения: 2048 (по умолчанию), 3072 или 4096; с key_type=ec, допустимые значения: 256 (по умолчанию), 384, или 521; игнорируется при key_type=ed25519.

  • ttl (string: "") - указывает запрашиваемую продолжительность жизни. Не может быть больше, чем значение max_ttl роли. Если не предоставлено, будет использоваться значение ttl роли. Обратите внимание, что значения роли по умолчанию соответствуют системным значениям, если они не установлены явно.

  • valid_principals (string: "") - указывает допустимые принципы, либо имена пользователей, либо имена хостов, для которых сертификат должен быть подписан.

  • cert_type (string: "user") - указывает тип сертификата, который должен быть создан; либо "пользователь", либо "хост".

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

  • critical_options (map<string|string>: "") - указывает карту критических опций, для которых сертификат должен быть подписан. По умолчанию отсутствуют.

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

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

{
  "key_type": "rsa",
  "key_bits":  2048
}

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/issue/my-role

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

{
  "request_id": "94fd1102-08a1-c207-0e3e-657e8f80c09e",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "issuer_id": "a38751e4-6cd1-f1b4-10ac-61eb2fcd3caf",
    "serial_number": "1e965817eb12a511",
    "signed_key": "ssh-rsa-cert-v01@openssh.com AAAAHHN...\n",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIBAAKCAQEAwer03vkQrPV+wWpbisJJv2CKqHmMz+Ej0ctLbhpOmR2CY9S9\n...\nQN351pgTphi6nlCkGPzkDuwvtxSxiCWXQcaxrHAL7MiJpPzkIBq1\n-----END RSA PRIVATE KEY-----\n",
    "private_key_type": "rsa"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

6. Проверка SSH OTP

Эта конечная точка проверяет, действителен ли указанный OTP. Это неаутентифицированная конечная точка.

Метод Путь

POST

/ssh/verify

6.1. Параметры

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

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

{
  "otp": "bad2b3-..."
}

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/ssh/verify

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

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "ip": "127.0.0.1",
    "username": "rajanadar"
  },
  "warnings": null,
  "auth": null
}