diff --git a/website/source/docs/http/secret/pki/index.html.md b/website/source/docs/http/secret/pki/index.html.md index caafae8723..642b4e805b 100644 --- a/website/source/docs/http/secret/pki/index.html.md +++ b/website/source/docs/http/secret/pki/index.html.md @@ -1449,8 +1449,3 @@ update your API calls accordingly. A `204` status code. -======= -The PKI secret backend has a full HTTP API. Please see the -[PKI secret backend API](/docs/http/secret/pki/index.html) for more -details. ->>>>>>> e54ffcd1... Break out API documentation for secret backends diff --git a/website/source/docs/http/secret/ssh/index.html.md b/website/source/docs/http/secret/ssh/index.html.md index 9563ca5427..d7fe1dcbd4 100644 --- a/website/source/docs/http/secret/ssh/index.html.md +++ b/website/source/docs/http/secret/ssh/index.html.md @@ -16,300 +16,222 @@ This documentation assumes the SSH backend is mounted at the `/ssh` path in Vault. Since it is possible to mount secret backends at any location, please update your API calls accordingly. -### /ssh/keys/ -#### POST +## Create/Update Key -
-
Description
-
- Creates or updates a named key. -
+This endpoint creates or updates a named key. -
Method
-
POST
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/keys/:name` | `204 (empty body)` | -
URL
-
`/ssh/keys/`
+### Parameters -
Parameters
-
- -
+- `name` `(string: )` – Specifies the name of the key to create. This + is part of the request URL. -
Returns
-
- A `204` response code. -
+- `key` `(string: )` – Specifies an SSH private key with appropriate + privileges on remote hosts. -#### DELETE +### Sample Payload -
-
Description
-
- Deletes a named key. -
+```json +{ + "key": "..." +} +``` -
Method
-
DELETE
+### Sample Request -
URL
-
`/ssh/keys/`
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/keys/my-key +``` -
Parameters
-
None
+## Delete Key -
Returns
-
- A `204` response code. -
+This endpoint deletes a named key. -### /ssh/roles/ -#### POST +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/ssh/keys/:name` | `204 (empty body)` | -
-
Description
-
- Creates or updates a named role. -
-
Method
-
POST
+### Parameters -
URL
-
`/ssh/roles/`
+- `name` `(string: )` – Specifies the name of the key to delete. This + is part of the request URL. -
Parameters
-
-
    -
  • - key - required for Dynamic Key type, N/A for - OTP type, N/A for CA type - (String) - Name of the registered key in Vault. Before creating the role, use - the `keys/` endpoint to create a named key. -
    • -
  • - admin_user - required for Dynamic Key type, N/A for OTP - type, N/A for CA type - (String) - Admin user at remote host. The shared key being registered should be - for this user and should have root or sudo privileges. Every time a - dynamic credential is generated for a client, Vault uses this admin - username to login to remote host and install the generated - credential. -
    • -
  • - default_user - required for Dynamic Key type, required - for OTP type, optional for CA type - (String) - Default username for which a credential will be generated. When the - endpoint 'creds/' is used without a username, this value will be used - as default username. Its recommended to create individual roles for - each username to ensure absolute isolation between usernames. +### Sample Request - For the CA type, if you wish this to be a valid principal, it must - also be in `allowed_users`. -
    • -
  • - cidr_list - optional for Dynamic Key type, optional for - OTP type, N/A for CA type - (String) - Comma separated list of CIDR blocks for which the role is applicable - for. CIDR blocks can belong to more than one role. -
    • -
  • - exclude_cidr_list - optional for Dynamic Key type, optional for - OTP type, N/A for CA type - (String) - Comma-separated list of CIDR blocks. IP addresses belonging to these - blocks are not accepted by the role. This is particularly useful when - big CIDR blocks are being used by the role and certain parts need to - be kept out. -
    • -
  • - port - optional for Dynamic Key type, optional for - OTP type, N/A for CA type - (Integer) - Port number for SSH connection. The default is '22'. Port number - does not play any role in OTP generation. For the 'otp' backend - type, this is just a way to inform the client about the port number - to use. The port number will be returned to the client by Vault - along with the OTP. -
    • -
  • - key_type - required for all types - (String) - Type of credentials generated by this role. Can be either `otp`, - `dynamic` or `ca`. -
    • -
  • - key_bits - optional for Dynamic Key type, N/A for OTP type, - N/A for CA type - (Integer) - Length of the RSA dynamic key in bits; can be either 1024 or 2048. - 1024 the default. -
    • -
  • - install_script - optional for Dynamic Key type, N/A for OTP type, - N/A for CA type - (String) - Script used to install and uninstall public keys in the target - machine. Defaults to the built-in script. -
    • -
  • - allowed_users - optional for all types - (String) - If this option is not specified, client can request for a credential - for any valid user at the remote host, including the admin user. If - only certain usernames are to be allowed, then this list enforces it. - If this field is set, then credentials can only be created for - `default_user` and usernames present in this list. Setting this - option will enable all the users with access this role to fetch - credentials for all other usernames in this list. Use with caution. -
    • -
  • - allowed_domains - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - (String) - If this option is not specified, client can request for a signed certificate for any - valid host. If only certain domains are allowed, then this list enforces it. - If this option is explicitly set to `*`, then credentials can be created - for any domain. -
    • -
  • - key_option_specs - optional for Dynamic Key type, N/A for OTP type, - N/A for CA type - (String) - Comma separated option specification which will be prefixed to RSA - keys in the remote host's authorized_keys file. N.B.: Vault does - not check this string for validity. -
    • -
  • - ttl - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - The Time To Live value provided as a string duration with time suffix. - Hour is the largest suffix. If not set, uses the system default value - or the value of `max_ttl`, whichever is shorter. -
    • -
  • - max_ttl - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - The maximum Time To Live provided as a string duration with time - suffix. Hour is the largest suffix. If not set, defaults to the system - maximum lease TTL. -
    • -
  • - allowed_critical_options - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - A comma-separated list of critical options that certificates can have when - signed. To allow any critical options, set this to an empty string. Will - default to allowing any critical options. -
    • -
  • - allowed_extensions - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - A comma-separated list of extensions that certificates can have when - signed. To allow any critical options, set this to an empty string. Will - default to allowing any extensions. -
    • -
  • - default_critical_options - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - A map of critical options certificates should have if none are provided - when signing. This field takes in key value pairs in JSON format. Note - that these are not restricted by `allowed_critical_options`. Defaults - to none. -
    • -
  • - default_extensions - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - A map of extensions certificates should have if none are provided when - signing. This field takes in key value pairs in JSON format. Note that - these are not restricted by `allowed_extensions`. Defaults to none. -
    • -
  • - allow_user_certificates - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If set, certificates are allowed to be signed for use as a 'user'. - Defaults to false. -
    • -
  • - allow_host_certificates - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If set, certificates are allowed to be signed for use as a 'host'. - Defaults to false. -
    • -
  • - allow_bare_domains - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If set, host certificates that are requested are allowed to use the base - domains listed in "allowed_users", e.g. "example.com". This - is a separate option as in some cases this can be considered a security - threat. Defaults to false. -
    • -
  • - allow_subdomains - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If set, host certificates that are requested are allowed to use - subdomains of those listed in "allowed_users". Defaults - to false. -
    • -
-
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/ssh/keys/my-key +``` -
Returns
-
- A `204` response code. -
+## Create Role -#### GET +This endpoint creates or updates a named role. -
-
Description
-
- Queries a named role. -
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/roles/:name` | `204 (empty body)` | -
Method
-
GET
+### Parameters -
URL
-
`/ssh/roles/`
+- `name` `(string: )` – Specifies the name of the role to create. This + is part of the request URL. -
Parameters
-
None
+- `key` `(string: "")` – Specifies the name of the registered key in Vault. + Before creating the role, use the `keys/` endpoint to create a named key. This + is required for "Dynamic Key" type. -
Returns
-
Note: these are examples only. For a dynamic key role: +- `admin_user` `(string: "")` – Specifies the admin user at remote host. The + shared key being registered should be for this user and should have root or + sudo privileges. Every time a dynamic credential is generated for a client, + Vault uses this admin username to login to remote host and install the + generated credential. This is required for Dynamic Key type. + +- `default_user` `(string: "")` – Specifies the default username for which a + credential will be generated. When the endpoint `creds/` is used without a + username, this value will be used as default username. Its recommended to + create individual roles for each username to ensure absolute isolation between + usernames. This is required for Dynamic Key type and OTP type. + + For the CA type, if you wish this to be a valid principal, it must also be + in `allowed_users`. + +- `cidr_list` `(string: "")` – Specifies a comma separated list of CIDR blocks + for which the role is applicable for.CIDR blocks can belong to more than one + role. + +- `exclude_cidr_list` `(string: "")` – Specifies a comma-separated list of CIDR + blocks. IP addresses belonging to these blocks are not accepted by the role. + This is particularly useful when big CIDR blocks are being used by the role + and certain parts need to be kept out. + +- `port` `(int: 22)` – Specifies the port number for SSH connection. Port number + does not play any role in OTP generation. For the `otp` backend type, this is + just a way to inform the client about the port number to use. The port number + will be returned to the client by Vault along with the OTP. + +- `key_type` `(string: )` – Specifies the type of credentials + generated by this role. This can be either `otp`, `dynamic` or `ca`. + +- `key_bits` `(int: 1024)` – Specifies the length of the RSA dynamic key in + bits. This can be either 1024 or 2048. + +- `install_script` + optional for Dynamic Key type, N/A for OTP type, + N/A for CA type + (String) + Script used to install and uninstall public keys in the target + machine. Defaults to the built-in script. + +- `allowed_users` `(string: "")` – If this option is not specified, client can + request for a credential for any valid user at the remote host, including the + admin user. If only certain usernames are to be allowed, then this list + enforces it. If this field is set, then credentials can only be created for + `default_user` and usernames present in this list. Setting this option will + enable all the users with access this role to fetch credentials for all other + usernames in this list. Use with caution. + +- `allowed_domains` `(string: "")` – If this option is not specified, client can + request for a signed certificate for any valid host. If only certain domains + are allowed, then this list enforces it. If this option is explicitly set to + `"*"`, then credentials can be created for any domain. + +- `key_option_specs` `(string: "")` – Specifies a aomma separated option + specification which will be prefixed to RSA keys in the remote host's + authorized_keys file. N.B.: Vault does not check this string for validity. + +- `ttl` `(string: "")` – Specifies the Time To Live value provided as a string + duration with time suffix. Hour is the largest suffix. If not set, uses the + system default value or the value of `max_ttl`, whichever is shorter. + +- `max_ttl` `(string: "")` – Specifies the maximum Time To Live provided as a + string duration with time suffix. Hour is the largest suffix. If not set, + defaults to the system maximum lease TTL. + +- `allowed_critical_options` `(string: "")` – Specifies a comma-separated list + of critical options that certificates can have when signed. To allow any + critical options, set this to an empty string. Will default to allowing any + critical options. + +- `allowed_extensions` `(string: "")` – Specifies a comma-separated list of + extensions that certificates can have when signed. To allow any critical + options, set this to an empty string. Will default to allowing any extensions. + +- `default_critical_options` `(map: "")` – Specifies a map of + critical options certificates should have if none are provided when signing. + This field takes in key value pairs in JSON format. Note that these are not + restricted by `allowed_critical_options`. Defaults to none. + +- `default_extensions` `(map: "")` – Specifies a map of + extensions certificates should have if none are provided when signing. This + field takes in key value pairs in JSON format. Note that these are not + restricted by `allowed_extensions`. Defaults to none. + +- `allow_user_certificates` `(bool: false)` – Specifies if certificates are + allowed to be signed for use as a 'user'. + +- `allow_host_certificates` `(bool: false)` – Specifies if certificates are + allowed to be signed for use as a 'host'. + +- `allow_bare_domains` `(bool: false)` – Specifies if host certificates that are + requested are allowed to use the base domains listed in "allowed_users", e.g. + "example.com". This is a separate option as in some cases this can be + considered a security threat. + +- `allow_subdomains` `(bool: false)` – Specifies if host certificates that are + requested are allowed to use subdomains of those listed in "allowed_users". + +### Sample Payload + +```json +{ + "key_type": "otp" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/roles/my-role +``` + +## Read Role + +This endpoint queries a named role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/ssh/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/ssh/roles/my-role +``` + +### Sample Response + +For a dynamic key role: ```json { @@ -322,9 +244,7 @@ update your API calls accordingly. } ``` -
- -
For an OTP role: +For an OTP role: ```json { @@ -334,8 +254,8 @@ update your API calls accordingly. "port": 22 } ``` -
-
For a CA role: + +For a CA role: ```json { @@ -351,89 +271,79 @@ update your API calls accordingly. "ttl": "4h" } ``` -
-#### LIST +## List Roles -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
+This endpoint returns a list of available roles. Only the role names are +returned, not any values. -
Method
-
LIST/GET
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/ssh/roles` | `200 application/json` | -
URL
-
`/ssh/roles` (LIST) or `/ssh/roles?list=true` (GET)
+### Sample Request -
Parameters
-
- None -
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/ssh/roles +``` -
Returns
-
+### Sample Response - ```json - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` +```json +{ + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` -
-
+## Delete Role -#### DELETE +This endpoint deletes a named role. -
-
Description
-
- Deletes a named role. -
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/ssh/roles/:name` | `204 (empty body)` | -
Method
-
DELETE
+### Parameters -
URL
-
`/ssh/roles/`
+- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. -
Parameters
-
None
+### Sample Request -
Returns
-
- A `204` response code. -
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + --data @payload.json \ + https://vault.rocks/v1/ssh/roles/my-role +``` -### /ssh/config/zeroaddress +## List Zero-Address Roles -#### GET +This endpoint returns the list of configured zero-address roles. -
-
Description
-
- Returns the list of configured zero-address roles. -
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/ssh/config/zeroaddress` | `200 application/json` | -
Method
-
GET
+### Sample Request -
URL
-
`/ssh/config/zeroaddress`
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/ssh/config/zeroaddress +``` -
Parameters
-
None
- -
Returns
-
+### Sample Response ```json { @@ -450,98 +360,94 @@ update your API calls accordingly. } ``` -
+## Configure Zero-Address Roles -#### POST +This endpoint configures zero-address roles. -
-
Description
-
- Configures zero-address roles. -
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/config/zeroaddress` | `204 (empty body)` | -
Method
-
POST
+### Parameters -
URL
-
`/ssh/config/zeroaddress`
+- `roles` `(string: )` – Specifies a string containing comma separated + list of role names which allows credentials to be requested for any IP + address. CIDR blocks previously registered under these roles will be ignored. -
Parameters
-
-
    -
  • - roles - required - A string containing comma separated list of role names which allows credentials to be requested - for any IP address. CIDR blocks previously registered under these roles will be ignored. -
    • -
-
+### Sample Payload -
Returns
-
- A `204` response code. -
+```json +{ + "roles": ["otp_key_role"] +} +``` -#### DELETE +### Sample Request -
-
Description
-
- Deletes the zero-address roles configuration. -
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/config/zeroaddress +``` -
Method
-
DELETE
+## Delete Zero-Address Role -
URL
-
`/ssh/config/zeroaddress`
+This endpoint deletes the zero-address roles configuration. -
Parameters
-
None
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/ssh/config/zeroaddress` | `204 (empty body)` | -
Returns
-
- A `204` response code. -
+### Sample Request +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/ssh/config/zeroaddress +``` -### /ssh/creds/ -#### POST +## Generate SSH Credentials -
-
Description
-
- Creates credentials for a specific username and IP with the - parameters defined in the given role. -
+This endpoint creates credentials for a specific username and IP with the +parameters defined in the given role. -
Method
-
POST
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/creds/:name` | `200 application/json` | -
URL
-
`/ssh/creds/`
+### Parameters -
Parameters
-
-
    -
  • - username - optional - (String) - Username on the remote host. -
    • -
  • - ip - required - (String) - IP of the remote host. -
    • -
-
+- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is part of the request URL. -
Returns
-
For a dynamic key role: +- `username` `(string: "")` – Specifies the username on the remote host. + +- `ip` `(string: )` – Specifies the IP of the remote host. + +### Sample Payload + +```json +{ + "ip": "1.2.3.4" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/creds/my-role +``` + +### Sample Response + +For a dynamic key role: ```json { @@ -549,26 +455,24 @@ update your API calls accordingly. "renewable": false, "lease_duration": 0, "data": { - "admin_user": "rajanadar", - "allowed_users": "", - "cidr_list": "x.x.x.x/y", - "default_user": "rajanadar", - "exclude_cidr_list": "x.x.x.x/y", - "install_script": "pretty_large_script", - "key": "5d9ee6a1-c787-47a9-9738-da243f4f69bf", - "key_bits": 1024, - "key_option_specs": "", - "key_type": "dynamic", - "port": 22 - }, + "admin_user": "rajanadar", + "allowed_users": "", + "cidr_list": "x.x.x.x/y", + "default_user": "rajanadar", + "exclude_cidr_list": "x.x.x.x/y", + "install_script": "pretty_large_script", + "key": "5d9ee6a1-c787-47a9-9738-da243f4f69bf", + "key_bits": 1024, + "key_option_specs": "", + "key_type": "dynamic", + "port": 22 + }, "warnings": null, "auth": null } ``` -
- -
For an OTP role: +For an OTP role: ```json { @@ -576,48 +480,50 @@ update your API calls accordingly. "renewable": false, "lease_duration": 2764800, "data": { - "ip": "127.0.0.1", - "key": "6d6411fd-f622-ea0a-7e2c-989a745cbbb2", - "key_type": "otp", - "port": 22, - "username": "rajanadar" - }, + "ip": "127.0.0.1", + "key": "6d6411fd-f622-ea0a-7e2c-989a745cbbb2", + "key_type": "otp", + "port": 22, + "username": "rajanadar" + }, "warnings": null, "auth": null } ``` -
+## List Roles by IP -### /ssh/lookup -#### POST +This endpoint lists all of the roles with which the given IP is associated. -
-
Description
-
- Lists all of the roles with which the given IP is associated. -
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/lookup` | `200 application/json` | -
Method
-
POST
+### Parameters -
URL
-
`/ssh/lookup`
+- `ip` `(string: )` – Specifies the IP of the remote host. -
Parameters
-
-
    -
  • - ip - required - (String) - IP of the remote host. -
    • -
-
+### Sample Payload -
Returns
-
An array of roles as a secret structure. +```json +{ + "ip": "1.2.3.4" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/lookup +``` + +### Sample Response + +An array of roles as a secret structure. ```json { @@ -625,237 +531,217 @@ update your API calls accordingly. "renewable": false, "lease_duration": 0, "data": { - "roles": ["fe6f61b7-7e4a-46a6-b2c8-0d530b8513df", "6d6411fd-f622-ea0a-7e2c-989a745cbbb2"] - }, + "roles": [ + "fe6f61b7-7e4a-46a6-b2c8-0d530b8513df", + "6d6411fd-f622-ea0a-7e2c-989a745cbbb2" + ] + }, "warnings": null, "auth": null } ``` -
-### /ssh/verify -#### POST +## Verify SSH OTP -
-
Description
-
- Verifies if the given OTP is valid. This is an unauthenticated - endpoint. -
+This endpoint verifies if the given OTP is valid. This is an unauthenticated +endpoint. -
Method
-
POST
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/verify` | `200 application/json` | -
URL
-
`/ssh/verify`
+## Parameters -
Parameters
-
-
    -
  • - otp - required - (String) - One-Time-Key that needs to be validated. -
    • -
-
+- `otp` `(string: )` – Specifies the One-Time-Key that needs to be + validated. -
Returns
-
A `200` response code for a valid OTP. +### Sample Payload + +```json +{ + "otp": "bad2b3-..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/verify + +### Sample Response ```json { "lease_id":"", "renewable":false, "lease_duration":0, - "data":{ - "ip":"127.0.0.1", - "username":"rajanadar" - }, + "data": { + "ip":"127.0.0.1", + "username":"rajanadar" + }, "warnings":null, "auth":null } ``` -
+## Submit CA Information -
A `400` BadRequest response code with 'OTP not found' message, for an invalid OTP.
+This endpoint allows submitting the CA information for the backend via an SSH +key pair. _If you have already set a certificate and key, they will be +overridden._ -### /ssh/config/ca -#### POST +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/config/ca` | `200/204 application/json` | -
-
Description
-
- Allows submitting the CA information for the backend via an SSH key pair. - _If you have already set a certificate and key, they will be overridden._

-
+### Parameters -
Method
-
POST
+- `private_key` `(string: "")` – Specifies the private key part the SSH CA key + pair; required if `generate_signing_key` is false. -
URL
-
`/ssh/config/ca`
+- `public_key` `(string: "")` – Specifies the public key part of the SSH CA key + pair; required if `generate_signing_key` is false. -
Parameters
-
-
    -
  • - private_key - optional - The private key part the SSH CA key pair; required if generate_signing_key is false. -
    • -
  • - public_key - optional - The public key part of the SSH CA key pair; required if generate_signing_key is false. -
    • -
  • - generate_signing_key - optional - Generate the signing key pair interally if true, otherwise use the private_key and public_key fields. - The generated public key will be returned so you can add it to your configuration. -
    • -
-
+- `generate_signing_key` `(bool: false)` – Specifies if Vault should generate + the signing key pair internally. The generated public key will be returned so + you can add it to your configuration. -
Returns
-
- A `204` response code. And if generate_signing_key was true: -
-
- ```json - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "public_key": "ssh-rsa AAAAHHNzaC1y...\n" - }, - "warnings": null - } - ``` -
-
+### Sample Payload -#### GET +```json +{ + "generate_signing_key": true +} +``` -
-
Description
-
- Reads the configured/generated public key. -
+### Sample Request -
Method
-
GET
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/config/ca +``` -
URL
-
`/ssh/config/ca`
+### Sample Response -
Parameters
-
None
+This will return a `204` response if `generate_signing_key` was unset or false. -
Returns
-
- ```json - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "public_key": "ssh-rsa AAAAHHNzaC1y...\n" - }, - "warnings": null - } - ``` -
-
+This will return a `200` response if `generate_signing_key` was true: -### /ssh/sign -#### POST +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "public_key": "ssh-rsa AAAAHHNzaC1y...\n" + }, + "warnings": null +} +``` -
-
Description
-
- Signs an SSH public key based on the supplied parameters, subject to the - restrictions contained in the role named in the endpoint. -
+## Read Public Key -
Method
-
POST
+This endpoint reads the configured/generated public key. -
URL
-
`/ssh/sign/`
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/ssh/config/ca` | `200 application/json` | -
Parameters
-
-
    -
  • - public_key - required - SSH public key that should be signed. -
    • -
  • - ttl - optional - Requested Time To Live. Cannot be greater than the role's `max_ttl` - value. If not provided, the role's `ttl` value will be used. Note that - the role values default to system values if not explicitly set. -
    • -
  • - valid_principals - optional - Valid principals, either usernames or hostnames, that the certificate - should be signed for. Defaults to none. -
    • -
  • - cert_type - optional - Type of certificate to be created; either "user" or "host". Defaults to - "user". -
    • -
  • - key_id - optional - Key id that the created certificate should have. If not specified, - the display name of the token will be used. -
    • -
  • - critical_options - optional - A map of the critical options that the certificate should be signed for. - Defaults to none. -
    • -
  • - extensions - optional - A map of the extensions that the certificate should be signed for. - Defaults to none -
    • -
-
+### Sample Request -
Returns
-
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/ssh/config/ca +``` - ```json - { - "lease_id": "ssh/sign/example/097bf207-96dd-0041-0e83-b23bd1923993", - "renewable": false, - "lease_duration": 21600, - "data": { - "serial_number": "f65ed2fd21443d5c", - "signed_key": "ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1y...\n" - }, - "auth": null - } - ``` +### Sample Response -
-
-======= -The SSH secret backend has a full HTTP API. Please see the -[SSH secret backend API](/docs/http/secret/ssh/index.html) for more -details. ->>>>>>> e54ffcd1... Break out API documentation for secret backends +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "public_key": "ssh-rsa AAAAHHNzaC1y...\n" + }, + "warnings": null +} +``` + +## Sigh SSH Key + +This endpoint signs an SSH public key based on the supplied parameters, subject +to the restrictions contained in the role named in the endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/sign/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to sign. This + is part of the request URL. + +- `public_key` `(string: )` – Specifies the SSH public key that should + be signed. + +- `ttl` `(string: "")` – Specifies the Requested Time To Live. Cannot be greater + than the role's `max_ttl` value. If not provided, the role's `ttl` value will + be used. Note that the role values default to system values if not explicitly + set. + +- `vauld_principals` `(string: "")` – Specifies valid principals, either + usernames or hostnames, that the certificate should be signed for. + +- `cert_type` `(string: "user")` – Specifies the type of certificate to be + created; either "user" or "host". + +- `key_id` `(string: "")` – Specifies the key id that the created certificate + should have. If not specified, the display name of the token will be used. + +- `critical_options` `(map: "")` – Specifies a map of the + critical options that the certificate should be signed for. Defaults to none. + +- `extension` `(map: "")` – Specifies a map of the extensions + that the certificate should be signed for. Defaults to none. + +### Sample Payload + +```json +{ + "public_key": "ssh-rsa ..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/sign/my-key +``` + +### Sample Response + +```json +{ + "lease_id": "ssh/sign/example/097bf207-96dd-0041-0e83-b23bd1923993", + "renewable": false, + "lease_duration": 21600, + "data": { + "serial_number": "f65ed2fd21443d5c", + "signed_key": "ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1y...\n" + }, + "auth": null +} +```