diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index 9518ab0e24..5d7ba26cca 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -7,6 +7,7 @@ $docs-font-size: 15px; body.layout-docs, body.layout-inner, body.layout-downloads, +body.layout-http, body.layout-intro { >.container { .col-md-8[role=main] { diff --git a/website/source/docs/http/index.html.md b/website/source/docs/http/index.html.md index a4c232e078..0fb620b3c8 100644 --- a/website/source/docs/http/index.html.md +++ b/website/source/docs/http/index.html.md @@ -8,6 +8,8 @@ description: |- # HTTP API +The Vault HTTP API is a + The Vault HTTP API gives you full access to Vault via HTTP. Every aspect of Vault can be controlled via this API. The Vault CLI uses the HTTP API to access Vault. @@ -170,5 +172,5 @@ The following HTTP status codes are used throughout the API. ## Limits -A maximum request size of 32MB is imposed to prevent a denial +A maximum request size of 32MB is imposed to prevent a denial of service attack with arbitrarily large requests. diff --git a/website/source/docs/http/secret/aws/index.html.md b/website/source/docs/http/secret/aws/index.html.md new file mode 100644 index 0000000000..d130c5f579 --- /dev/null +++ b/website/source/docs/http/secret/aws/index.html.md @@ -0,0 +1,357 @@ +--- +layout: "http" +page_title: "HTTP API" +sidebar_current: "docs-http-secret-aws" +description: |- + TODO +--- + +# AWS Secret Backend HTTP API + +This is the API documentation for the Vault AWS secret backend. For general +information about the usage and operation of the AWS backend, please see the +[Vault AWS backend documentation](/docs/secrets/aws/index.html). + +This documentation assumes the AWS backend is mounted at the `/aws` path in +Vault. Since it is possible to mount secret backends at any location, please +update your API calls accordingly. + +## Configure Root IAM Credentials + +This endpoint configures the root IAM credentials to communicate with AWS. There +are multiple ways to pass root IAM credentials to the Vault server, specified +below with the highest precedence first. If credentials already exist, this will +overwrite them. + +- Static credentials provided to the API as a payload + +- Credentials in the `AWS_ACCESS_KEY`, `AWS_SECRET_KEY`, and `AWS_REGION` + environment variables **on the server** + +- Querying the EC2 metadata service if the **Vault server** is on EC2 and has + querying capabilities + +At present, this endpoint does not confirm that the provided AWS credentials are +valid AWS credentials with proper permissions. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/aws/config/root` | `204 (empty body)` | + +### Parameters + +- `access_key` `(string: )` – Specifies the AWS access key ID. + +- `secret_key` `(string: )` – Specifies the AWS secret access key. + +- `region` `(string: )` – Specifies the AWS region. + +### Sample Payload + +```json +{ + "access_key": "AKIA...", + "secret_key": "2J+...", + "region": "us-east-1" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/aws/config/root +``` + +## Configure Lease + +This endpoint configures lease settings for the AWS secret backend. It is +optional, as there are default values for `lease` and `lease_max`. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/aws/config/lease` | `204 (empty body)` | + +### Parameters + +- `lease` `(string: )` – Specifies the lease value provided as a + string duration with time suffix. "h" (hour) is the largest suffix. + +- `lease_max` `(string: )` – Specifies the maximum lease value + provided as a string duration with time suffix. "h" (hour) is the largest + suffix. + +### Sample Payload + +```json +{ + "lease": "30m", + "lease_max": "12h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/aws/config/lease +``` + +## Read Lease + +This endpoint returns the current lease settings for the AWS secret backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/aws/config/lease` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/aws/config/lease +``` + +### Sample Response + +```json +{ + "data": { + "lease": "30m0s", + "lease_max": "12h0m0s" + } +} +``` + +## Create/Update Role + +This endpoint creates or updates the role with the given `name`. If a role with +the name does not exist, it will be created. If the role exists, it will be +updated with the new attributes. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/aws/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create. This + is part of the request URL. + +- `policy` `(string: )` – Specifies the IAM policy + in JSON format. + +- `arn` `(string: )` – Specifies the full ARN + reference to the desired existing policy. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/aws/roles/example-role +``` + +### Sample Payloads + +Using an inline IAM policy: + +```json +{ + "policy": "{\"Version\": \"...\"}", +} +``` + +Using an ARN: + +```json +{ + "arn": "arn:aws:iam::123456789012:user/David" +} +``` + +## Read Role + +This endpoint queries an existing role by the given name. If the role does not +exist, a 404 is returned. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/aws/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/aws/roles/example-role +``` + +### Sample Responses + +For an inline IAM policy: + +```json +{ + "data": { + "policy": "{\"Version\": \"...\"}" + } +} +``` + +For an ARN: + +```json +{ + "data": { + "arn": "arn:aws:iam::123456789012:user/David" + } +} +``` + +## List Roles + +This endpoint lists all existing roles in the backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/aws/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/aws/roles +``` + +### Sample Response + +```json +{ + "data": { + "keys": [ + "example-role" + ] + } +} +``` + +## Delete Role + +This endpoint deletes an existing role by the given name. If the role does not +exist, a 404 is returned. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELET` | `/aws/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/aws/roles/example-role +``` + +## Generate IAM Credentials + +This endpoint generates dynamic IAM credentials based on the named role. This +role must be created before queried. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/aws/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to generate + credentials againts. This is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/aws/creds/example-role +``` + +### Sample Response + +```json +{ + "data": { + "access_key": "AKIA...", + "secret_key": "xlCs...", + "security_token": null + } +} +``` + +## Generate IAM with STS + +This generates a dynamic IAM credential with an STS token based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/aws/sts/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role against which + to create this STS credential. This is part of the request URL. + +- `ttl` `(string: "3600s")` – Specifies the TTL for the use of the STS token. + This is specified as a string with a duration suffix. + +### Sample Payload + +```json +{ + "ttl": "5m" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/aws/sts/example-role +``` + +### Sample Response + +```json +{ + "data": { + "access_key": "AKIA...", + "secret_key": "xlCs...", + "security_token": "429255" + } +} +``` diff --git a/website/source/docs/http/secret/cassandra/index.html.md b/website/source/docs/http/secret/cassandra/index.html.md new file mode 100644 index 0000000000..a9f502ac53 --- /dev/null +++ b/website/source/docs/http/secret/cassandra/index.html.md @@ -0,0 +1,245 @@ +--- +layout: "http" +page_title: "Cassandra Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-cassandra" +description: |- + TODO +--- + +# Cassandra Secret Backend HTTP API + +This is the API documentation for the Vault Cassandra secret backend. For +general information about the usage and operation of the Cassandra backend, +please see the +[Vault Cassandra backend documentation](/docs/secrets/cassandra/index.html). + +This documentation assumes the Cassandra backend is mounted at the `/cassandra` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the connection information used to communicate with +Cassandra. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/cassandra/config/connection` | `204 (empty body)` | + +### Parameters + +- `hosts` `(string: )` – Specifies a set of comma-delineated Cassandra + hosts to connect to. + +- `username` `(string: )` – Specifies the username to use for + superuser access. + +- `password` `(string: )` – Specifies the password corresponding to + the given username. + +- `tls` `(bool: true)` – Specifies whether to use TLS when connecting to + Cassandra. + +- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the + server certificate when using TLS. + +- `pem_bundle` `(string: "")` – Specifies concatenated PEM blocks containing a + certificate and private key; a certificate, private key, and issuing CA + certificate; or just a CA certificate. + +- `pem_json` `(string: "")` – Specifies JSON containing a certificate and + private key; a certificate, private key, and issuing CA certificate; or just a + CA certificate. For convenience format is the same as the output of the + `issue` command from the `pki` backend; see + [the pki documentation](/docs/secrets/pki/index.html). + +- `protocol_version` `(int: 2)` – Specifies the CQL protocol version to use. + +- `connect_timeout` `(string: "5s")` – Specifies the connection timeout to use. + +TLS works as follows: + +- If `tls` is set to true, the connection will use TLS; this happens + automatically if `pem_bundle`, `pem_json`, or `insecure_tls` is set + +- If `insecure_tls` is set to true, the connection will not perform verification + of the server certificate; this also sets `tls` to true + +- If only `issuing_ca` is set in `pem_json`, or the only certificate in + `pem_bundle` is a CA certificate, the given CA certificate will be used for + server certificate verification; otherwise the system CA certificates will be + used + +- If `certificate` and `private_key` are set in `pem_bundle` or `pem_json`, + client auth will be turned on for the connection + +`pem_bundle` should be a PEM-concatenated bundle of a private key + client +certificate, an issuing CA certificate, or both. `pem_json` should contain the +same information; for convenience, the JSON format is the same as that output by +the issue command from the PKI backend. + +### Sample Payload + +```json +{ + "hosts": "cassandra1.local", + "username": "user", + "password": "pass" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/cassandra/config/connection +``` + +## Create Role + +This endpoint creates or updates the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/cassandra/roles/:name` | `204 (empty body)` | + +### Parameters + +- `creation_cql` `(string: "")` – Specifies the CQL statements executed to + create and configure the new user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The '{{username}}' and + '{{password}}' values will be substituted; it is required that these + parameters are in single quotes. The default creates a non-superuser user with + no authorization grants. + +- `rollback_cql` `(string: "")` – Specifies the CQL statements executed to + attempt a rollback if an error is encountered during user creation. The + default is to delete the user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The '{{username}}' and + '{{password}}' values will be substituted; it is required that these + parameters are in single quotes. + +- `lease` `(string: "")` – Specifies the lease value provided as a string + duration with time suffix. "h" hour is the largest suffix. + +- `consistency` `(string: "Quorum")` – Specifies the consistency level value + provided as a string. Determines the consistency level used for operations + performed on the Cassandra database. + +### Sample Payload + +```json +{ + "creation_cql": "CREATE USER ..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/cassandra/roles/my-role +``` + +
Returns
+
+ A `204` response code. +
+ + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/cassandra/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/cassandra/roles/my-role +``` + +### Sample Response + +```json +{ + "data": { + "creation_cql": "CREATE USER...", + "rollback_cql": "DROP USER...", + "lease": "12h", + "consistency": "Quorum" + } +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/cassandra/roles/:name` | `204 (no body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/cassandra/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/cassandra/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \Z + https://vault.rocks/v1/cassandra/creds/my-role +``` + +### Sample Response + +```json +{ + "data": { + "username": "vault-root-1430158508-126", + "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" + } +} +``` diff --git a/website/source/docs/http/secret/consul/index.html.md b/website/source/docs/http/secret/consul/index.html.md new file mode 100644 index 0000000000..674c9fe206 --- /dev/null +++ b/website/source/docs/http/secret/consul/index.html.md @@ -0,0 +1,201 @@ +--- +layout: "http" +page_title: "Consul Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-consul" +description: |- + TODO +--- + +# Consul Secret Backend HTTP API + +This is the API documentation for the Vault Consul secret backend. For general +information about the usage and operation of the Consul backend, please see the +[Vault Consul backend documentation](/docs/secrets/consul/index.html). + +This documentation assumes the Consul backend is mounted at the `/consul` path +in Vault. Since it is possible to mount secret backends at any location, please +update your API calls accordingly. + +## Configure Access + +This endpoint configures the access information for Consul. This access +information is used so that Vault can communicate with Consul and generate +Consul tokens. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/consul/config/access` | `204 (empty body)` | + +### Parameters + +- `address` `(string: )` – Specifies the address of the Consul + instance, provided as `"host:port"` like `"127.0.0.1:8500"`. + +- `scheme` `(string: "http")` – Specifies the URL scheme to use. + +- `token` `(string: )` – Specifies the Consul ACL token to use. This + must be a management type token. + +### Sample Payload + +```json +{ + "address": "127.0.0.1:8500", + "scheme": "https", + "token": "adha..." +} +``` + +### Sample Request + +``` +$ curl \ + --request POST \ + --header "X-Vault-Token: ..." \ + --data @payload.json \ + https://vault.rocks/v1/consul/config/access +``` + +## Create/Update Role + +This endpoint creates or updates the Consul role definition. If the role does +not exist, it will be created. If the role already exists, it will receive +updated attributes. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/consul/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of an existing role against + which to create this Consul credential. This is part of the request URL. + +- `lease` `(string: "")` – Specifies the lease for this role. This is provided + as a string duration with a time suffix like `"30s"` or `"1h"`. If not + provided, the default Vault lease is used. + +- `policy` `(string: )` – Specifies the base64 encoded ACL policy. The + ACL format can be found in the [Consul ACL + documentation](https://www.consul.io/docs/internals/acl.html). This is + required unless the `token_type` is `management`. + +- `token_type` `(string: "client")` - Specifies the type of token to create when + using this role. Valid values are `"client"` or `"management"`. + +### Sample Payload + +To create management tokens: + +```json +{ + "token_type": "management" +} +``` + +To create a client token with a custom policy: + +```json +{ + "policy": "abd2...==" +} +``` + +### Sample Request + +``` +$ curl \ + --request POST \ + --header "X-Vault-Token: ..." \ + --data @payload.json \ + https://vault.rocks/v1/consul/roles/example-role +``` + +## Read Role + +This endpoint queries for information about a Consul role with the given name. +If no role exists with that name, a 404 is returned. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/consul/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to query. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/consul/roles/example-role +``` + +### Sample Response + +```json +{ + "data": { + "policy": "abd2...==", + "lease": "1h0m0s", + "token_type": "client" + } +} +``` + +## Delete Role + +This endpoint deletes a Consul role with the given name. Even if the role does +not exist, this endpoint will still return a successful response. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/consul/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --request DELETE \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/consul/roles/example-role +``` + +## Generate Credential + +This endpoint generates a dynamic Consul token based on the given role +definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/consul/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of an existing role against + which to create this Consul credential. This is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/consul/creds/example-role +``` + +### Sample Response + +```json +{ + "data": { + "token": "973a31ea-1ec4-c2de-0f63-623f477c2510" + } +} +``` diff --git a/website/source/docs/http/secret/cubbyhole/index.html.md b/website/source/docs/http/secret/cubbyhole/index.html.md new file mode 100644 index 0000000000..77b31ca4eb --- /dev/null +++ b/website/source/docs/http/secret/cubbyhole/index.html.md @@ -0,0 +1,155 @@ +--- +layout: "http" +page_title: "Cubbyhole Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-cubbyhole" +description: |- + TODO +--- + +# Cubbyhole Secret Backend HTTP API + +This is the API documentation for the Vault Cubbyhole secret backend. For +general information about the usage and operation of the Cubbyhole backend, +please see the +[Vault Cubbyhole backend documentation](/docs/secrets/cubbyhole/index.html). + +This documentation assumes the Cubbyhole backend is mounted at the `/cubbyhole` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Read Secret + +This endpoint retrieves the secret at the specified location. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/cubbyhole/:path` | `200 application/json` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to read. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/cubbyhole/my-secret +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "foo": "bar" + }, + "lease_duration": 0, + "lease_id": "", + "renewable": false +} +``` + +## List Secrets + +This endpoint returns a list of secret entries at the specified location. +Folders are suffixed with `/`. The input must be a folder; list on a file will +not return a value. The values themselves are not accessible via this command. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `List` | `/cubbyhole/:path` | `200 application/json` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secrets to list. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/cubbyhole/my-secret +``` + +### Sample Response + +The example below shows output for a query path of `cubbyhole/` when there are +secrets at `cubbyhole/foo` and `cubbyhole/foo/bar`; note the difference in the +two entries. + +```json +{ + "auth": null, + "data": { + "keys": ["foo", "foo/"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Create/Update Secret + +This endpoint stores a secret at the specified location. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/cubbyhole/:path` | `204 (empty body)` | +| `PUT` | `/cubbyhole/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secrets to + create/update. This is specified as part of the URL. + +- `:key` `(string: "")` – Specifies a key, paired with an associated value, to + be held at the given location. Multiple key/value pairs can be specified, and + all will be returned on a read operation. A key called `ttl` will trigger some + special behavior; see above for details. + +### Sample Payload + +```json +{ + "foo": "bar", + "zip": "zap" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/cubbyhole/my-secret +``` + +## Delete Secret + +This endpoint deletes the secret at the specified location. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/cubbyhole/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to delete. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/cubbyhole/my-secret +``` diff --git a/website/source/docs/http/secret/generic/index.html.md b/website/source/docs/http/secret/generic/index.html.md new file mode 100644 index 0000000000..6e1b33ea9d --- /dev/null +++ b/website/source/docs/http/secret/generic/index.html.md @@ -0,0 +1,159 @@ +--- +layout: "http" +page_title: "Generic Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-generic" +description: |- + TODO +--- + +# Generic Secret Backend HTTP API + +This is the API documentation for the Vault Generic secret backend. For general +information about the usage and operation of the Generic backend, please see +the [Vault Generic backend documentation](/docs/secrets/generic/index.html). + +This documentation assumes the Generic backend is mounted at the `/secret` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Read Secret + +This endpoint retrieves the secret at the specified location. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/secret/:path` | `200 application/json` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to read. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/secret/my-secret +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "foo": "bar" + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## List Secrets + +This endpoint returns a list of key names at the specified location. Folders are +suffixed with `/`. The input must be a folder; list on a file will not return a +value. Note that no policy-based filtering is performed on keys; do not encode +sensitive information in key names. The values themselves are not accessible via +this command. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/secret/:path` | `200 application/json` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secrets to list. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/secret/my-secret +``` + +### Sample Response + +The example below shows output for a query path of `secret/` when there are +secrets at `secret/foo` and `secret/foo/bar`; note the difference in the two +entries. + +```json +{ + "auth": null, + "data": { + "keys": ["foo", "foo/"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Create/Update Secret + +This endpoint stores a secret at the specified location. If the value does not +yet exist, the calling token must have an ACL policy granting the `create` +capability. If the value already exists, the calling token must have an ACL +policy granting the `update` capability. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/secret/:path` | `204 (empty body)` | +| `PUT` | `/secret/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secrets to + create/update. This is specified as part of the URL. + +- `:key` `(string: "")` – Specifies a key, paired with an associated value, to + be held at the given location. Multiple key/value pairs can be specified, and + all will be returned on a read operation. A key called `ttl` will trigger some + special behavior; see above for details. + +### Sample Payload + +```json +{ + "foo": "bar", + "zip": "zap" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/secret/my-secret +``` + +## Delete Secret + +This endpoint deletes the secret at the specified location. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/secret/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to delete. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/secret/my-secret +``` diff --git a/website/source/docs/http/secret/index.html.md b/website/source/docs/http/secret/index.html.md new file mode 100644 index 0000000000..51dfc15318 --- /dev/null +++ b/website/source/docs/http/secret/index.html.md @@ -0,0 +1,19 @@ +--- +layout: "http" +page_title: "HTTP API" +sidebar_current: "docs-http-secret" +description: |- + Each secret backend publishes its own set of API paths and methods. These + endpoints are documented in this section. +--- + +# Secret Backends + +Each secret backend publishes its own set of API paths and methods. These +endpoints are documented in this section. Secret backends are mounted at a path, +but the documentation will assume the default mount points for simplicity. If +you are mounting at a different path, you should adjust your API calls +accordingly. + +For the API documentation for a specific secret backend, please choose a secret +backend from the navigation. diff --git a/website/source/docs/http/secret/mongodb/index.html.md b/website/source/docs/http/secret/mongodb/index.html.md new file mode 100644 index 0000000000..4ddceee928 --- /dev/null +++ b/website/source/docs/http/secret/mongodb/index.html.md @@ -0,0 +1,344 @@ +--- +layout: "http" +page_title: "MongoDB Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-mongodb" +description: |- + TODO +--- + +# MongoDB Secret Backend HTTP API + +This is the API documentation for the Vault MongoDB secret backend. For general +information about the usage and operation of the MongoDB backend, please see +the [Vault MongoDB backend documentation](/docs/secrets/mongodb/index.html). + +This documentation assumes the MongoDB backend is mounted at the `/mongodb` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the standard connection string (URI) used to +communicate with MongoDB. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mongodb/config/connection` | `200 application/json` | + +### Parameters + +- `url` `(string: )` – Specifies the MongoDB standard connection + string (URI). + +- `verify_connection` `(bool: true)` – Specifies if the connection is verified + during initial configuration. + +### Sample Payload + +```json +{ + "url": "mongodb://db1.example.net,db2.example.net:2500/?replicaSet=test" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mongodb/config/connection +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": null, + "wrap_info": null, + "warnings": [ + "Read access to this endpoint should be controlled via ACLs as it will return the connection URI as it is, including passwords, if any." + ], + "auth": null +} +``` + +## Read Connection + +This endpoint queries the connection configuration. Access to this endpoint +should be controlled via ACLs as it will return the connection URI as it is, +including passwords, if any. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mongodb/config/connection` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mongodb/config/connection +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "uri": "mongodb://admin:Password!@mongodb.acme.com:27017/admin?ssl=true" + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Configure Lease + +This endpoint configures the default lease TTL settings for credentials +generated by the mongodb backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mongodb/config/lease` | `204 (empty body)` | + +### Parameters + +- `lease` `(string: )` – Specifies the lease value provided as a + string duration with time suffix. "h" (hour) is the largest suffix. + +- `lease_max` `(string: )` – Specifies the maximum lease value + provided as a string duration with time suffix. "h" (hour) is the largest + suffix. + +### Sample Payload + +```json +{ + "lease": "12h", + "lease_max": "24h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mongodb/config/lease +``` + +## Read Lease + +This endpoint queries the lease configuration. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mongodb/config/lease` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mongodb/config/lease +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "max_ttl": 60, + "ttl": 60 + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Create Role + +This endpoint creates or updates a role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mongodb/roles/:name` | `204 (empty body)` | + +### Parameters + +- `db` `(string: )` – Specifies the name of the database users should + be created in for this role. + +- `roles` `(string: "")` – Specifies the MongoDB roles to assign to the users + generated for this role. + +### Sample Payload + +```json +{ + "db": "my-db", + "roles": "[\"readWrite\",{\"db\":\"bar\",\"role\":\"read\"}]" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mongodb/roles/my-role +``` + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mongodb/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mongodb/roles/my-role +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "db": "foo", + "roles": "[\"readWrite\",{\"db\":\"bar\",\"role\":\"read\"}]" + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## List Roles + +This endpoint returns a list of available roles. Only the role names are +returned, not any values. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/mongodb/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/mongodb/roles +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "keys": [ + "dev", + "prod" + ] + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/mongodb/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/mongodb/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mongodb/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mongodb/creds/my-role +``` + +### Sample Response + +```json +{ + "lease_id": "mongodb/creds/readonly/e64e79d8-9f56-e379-a7c5-373f9b4ee3d8", + "renewable": true, + "lease_duration": 3600, + "data": { + "db": "foo", + "password": "de0f7b50-d700-54e5-4e81-5c3724283999", + "username": "vault-token-b32098cb-7ff2-dcf5-83cd-d5887cedf81b" + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` diff --git a/website/source/docs/http/secret/mssql/index.html.md b/website/source/docs/http/secret/mssql/index.html.md new file mode 100644 index 0000000000..6099ff0272 --- /dev/null +++ b/website/source/docs/http/secret/mssql/index.html.md @@ -0,0 +1,244 @@ +--- +layout: "http" +page_title: "MSSQL Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-mssql" +description: |- + TODO +--- + +# MSSQL Secret Backend HTTP API + +This is the API documentation for the Vault MSSQL secret backend. For general +information about the usage and operation of the MSSQL backend, please see +the [Vault MSSQL backend documentation](/docs/secrets/mssql/index.html). + +This documentation assumes the MSSQL backend is mounted at the `/mssql` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the connection DSN used to communicate with Microsoft +SQL Server. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mssql/config/connection` | `204 (empty body)` | + +### Parameters + +- `connection_string` `(string: )` – Specifies the MSSQL DSN. + +- `max_open_connections` `(int: 2)` – Specifies the maximum number of open + connections to the database. + +- `max_idle_connections` `(int: 0)` – Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +### Sample Payload + +```json +{ + "connection_string": "Server=myServerAddress;Database=myDataBase;User Id=myUsername; Password=myPassword;" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mssql/config/connection +``` + +## Configure Lease + +This endpoint configures the lease settings for generated credentials. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mysql/config/lease` | `204 (empty body)` | + +### Parameters + +- `lease` `(string: )` – Specifies the lease value provided as a + string duration with time suffix. "h" (hour) is the largest suffix. + +- `lease_max` `(string: )` – Specifies the maximum lease value + provided as a string duration with time suffix. "h" (hour) is the largest + suffix. + +### Sample Payload + +```json +{ + "lease": "12h", + "lease_max": "24h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mssql/config/lease +``` + +## Create Role + +This endpoint creates or updates the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mssql/roles/:name` | `204 (empty body)` | + +### Parameters + +- `sql` `(string: )` – Specifies the SQL statements executed to create + and configure the role. The '{{name}}' and '{{password}}' values will be + substituted. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. + +### Sample Payload + +```json +{ + "sql": "CREATE LOGIN ..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mssql/roles/my-role +``` + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mssql/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mssql/roles/my-role +``` + +### Sample Response + +```json +{ + "data": { + "sql": "CREATE LOGIN..." + } +} +``` + +## List Roles + +This endpoint returns a list of available roles. Only the role names are +returned, not any values. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/mssql/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/mssql/roles +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/mssql/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/mssql/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mssql/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mssql/creds/my-role +``` + +### Sample Response + +```json +{ + "data": { + "username": "root-a147d529-e7d6-4a16-8930-4c3e72170b19", + "password": "ee202d0d-e4fd-4410-8d14-2a78c5c8cb76" + } +} +``` diff --git a/website/source/docs/http/secret/mysql/index.html.md b/website/source/docs/http/secret/mysql/index.html.md new file mode 100644 index 0000000000..c543ddb03b --- /dev/null +++ b/website/source/docs/http/secret/mysql/index.html.md @@ -0,0 +1,265 @@ +--- +layout: "http" +page_title: "MySQL Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-mysql" +description: |- + TODO +--- + +# MySQL Secret Backend HTTP API + +This is the API documentation for the Vault MySQL secret backend. For general +information about the usage and operation of the MySQL backend, please see +the [Vault MySQL backend documentation](/docs/secrets/mysql/index.html). + +This documentation assumes the MySQL backend is mounted at the `/mysql` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the connection DSN used to communicate with MySQL. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mysql/config/connection` | `204 (empty body)` | + +### Parameters + +- `connection_url` `(string: )` – Specifies the MySQL DSN. + +- `max_open_connections` `(int: 2)` – Specifies the maximum number of open + connections to the database. + +- `max_idle_connections` `(int: 0)` – Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `verify_connection` `(bool: true)` – Specifies if the connection is verified + during initial configuration. + +### Sample Payload + +```json +{ + "connection_url": "mysql:host=localhost;dbname=testdb" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mysql/config/connection +``` + +## Configure Lease + +This endpoint configures the lease settings for generated credentials. If not +configured, leases default to 1 hour. This is a root protected endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mysql/config/lease` | `204 (empty body)` | + +### Parameters + +- `lease` `(string: )` – Specifies the lease value provided as a + string duration with time suffix. "h" (hour) is the largest suffix. + +- `lease_max` `(string: )` – Specifies the maximum lease value + provided as a string duration with time suffix. "h" (hour) is the largest + suffix. + +### Sample Payload + +```json +{ + "lease": "12h", + "lease_max": "24h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mysql/config/lease +``` + +## Create Role + +This endpoint creates or updates the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mysql/roles/:name` | `204 (empty body)` | + +### Parameters + +- `sql` `(string: )` – Specifies the SQL statements executed to create + and configure a user. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The '{{name}}' and + '{{password}}' values will be substituted. + +- `revocation_sql` `(string: "")` – Specifies the SQL statements executed to + revoke a user. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The '{{name}}' value will be + substituted. + +- `rolename_length` `(int: 4)` – Specifies how many characters from the role + name will be used to form the mysql username interpolated into the '{{name}}' + field of the sql parameter. + +- `displayname_length` `(int: 4)` – Specifies how many characters from the token + display name will be used to form the mysql username interpolated into the + '{{name}}' field of the sql parameter. + +- `username_length` `(int: 16)` – Specifies the maximum total length in + characters of the mysql username interpolated into the '{{name}}' field of the + sql parameter. + +### Sample Payload + +```json +{ + "sql": "CREATE USER ..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mysql/roles/my-role +``` + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mysql/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mysql/roles/my-role +``` + +### Sample Response + +```json +{ + "data": { + "sql": "CREATE USER..." + } +} +``` + +## List Roles + +This endpoint returns a list of available roles. Only the role names are +returned, not any values. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/mysql/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/mysql/roles +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/mysql/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/mysql/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mysql/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mysql/creds/my-role +``` + +### Sample Response + +```json +{ + "data": { + "username": "user-role-aefa63", + "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" + } +} +``` diff --git a/website/source/docs/http/secret/pki/index.html.md b/website/source/docs/http/secret/pki/index.html.md new file mode 100644 index 0000000000..df9ae26f42 --- /dev/null +++ b/website/source/docs/http/secret/pki/index.html.md @@ -0,0 +1,1456 @@ +--- +layout: "http" +page_title: "PKI Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-pki" +description: |- + TODO +--- + +# PKI Secret Backend HTTP API + +This is the API documentation for the Vault PKI secret backend. For general +information about the usage and operation of the PKI backend, please see the +[Vault PKI backend documentation](/docs/secrets/pki/index.html). + +This documentation assumes the PKI backend is mounted at the `/pki` path in +Vault. Since it is possible to mount secret backends at any location, please +update your API calls accordingly. + + +### /pki/ca(/pem) +#### GET + +
+
Description
+
+ Retrieves the CA certificate *in raw DER-encoded form*. This is a bare + endpoint that does not return a standard Vault data structure. If `/pem` is + added to the endpoint, the CA certificate is returned in PEM format.
+
This is an unauthenticated endpoint. +
+ +
Method
+
GET
+ +
URL
+
`/pki/ca(/pem)`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ``` + + ``` + +
+
+ +### /pki/ca_chain +#### GET + +
+
Description
+
+ Retrieves the CA certificate chain, including the CA *in PEM format*. This + is a bare endpoint that does not return a standard Vault data structure. +

This is an unauthenticated endpoint. +
+ +
Method
+
GET
+ +
URL
+
`/pki/ca_chain`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ``` + + ``` + +
+
+ +### /pki/cert/ +#### GET + +
+
Description
+
+ Retrieves one of a selection of certificates. Valid values: `ca` for the CA + certificate, `crl` for the current CRL, `ca_chain` for the CA trust chain + or a serial number in either hyphen-separated or colon-separated octal + format. This endpoint returns the certificate in PEM formatting in the + `certificate` key of the JSON object.

This is an unauthenticated endpoint. +
+ +
Method
+
GET
+ +
URL
+
`/pki/cert/`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIGmDCCBYCgAwIBAgIHBzEB3fTzhTANBgkqhkiG9w0BAQsFADCBjDELMAkGA1UE\n..." + } + } + ... + ``` + +
+
+ +### /pki/certs/ +#### LIST + +
+
Description
+
+ Returns a list of the current certificates by serial number only. +
+ +
Method
+
LIST/GET
+ +
URL
+
`/pki/certs` (LIST) or `/pki/certs?list=true` (GET)
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "lease_id":"", + "renewable":false, + "lease_duration":0, + "data":{ + "keys":[ + "17:67:16:b0:b9:45:58:c0:3a:29:e3:cb:d6:98:33:7a:a6:3b:66:c1", + "26:0f:76:93:73:cb:3f:a0:7a:ff:97:85:42:48:3a:aa:e5:96:03:21" + ] + }, + "wrap_info":null, + "warnings":null, + "auth":null + } + ... + ``` + +
+
+ +### /pki/config/ca +#### POST + +
+
Description
+
+ Allows submitting the CA information for the backend via a PEM file + containing the CA certificate and its private key, concatenated. Not needed + if you are generating a self-signed root certificate, and not used if you + have a signed intermediate CA certificate with a generated key (use the + `/pki/intermediate/set-signed` endpoint for that). _If you have already set + a certificate and key, they will be overridden._

The information + can be provided from a file via a `curl` command similar to the + following:
+ + ```text + $ curl \ + -H "X-Vault-Token:06b9d..." \ + -X POST \ + --data "@cabundle.json" \ + http://127.0.0.1:8200/v1/pki/config/ca + ``` + + Note that if you provide the data through the HTTP API it must be + JSON-formatted, with newlines replaced with `\n`, like so: + + ```javascript + { + "pem_bundle": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END CERTIFICATE-----" + } + ``` +
+ +
Method
+
POST
+ +
URL
+
`/pki/config/ca`
+ +
Parameters
+
+
    +
  • + pem_bundle + required + The key and certificate concatenated in PEM format. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+
+ +### /pki/config/crl +#### GET + +
+
Description
+
+ Allows getting the duration for which the generated CRL should be marked + valid. +
+ +
Method
+
GET
+ +
URL
+
`/pki/config/crl`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "expiry": "72h" + }, + "auth": null + } + ``` + +
+
+ +#### POST + +
+
Description
+
+ Allows setting the duration for which the generated CRL should be marked + valid. +
+ +
Method
+
POST
+ +
URL
+
`/pki/config/crl`
+ +
Parameters
+
+
    +
  • +
  • + expiry + required + The time until expiration. Defaults to `72h`. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+
+ +### /pki/config/urls + +#### GET + +
+
Description
+
+ Fetch the URLs to be encoded in generated certificates. +
+ +
Method
+
GET
+ +
URL
+
`/pki/config/urls`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "issuing_certificates": [, ], + "crl_distribution_points": [, ], + "ocsp_servers": [, ], + }, + "auth": null + } + ``` + +
+
+ +#### POST + +
+
Description
+
+ Allows setting the issuing certificate endpoints, CRL distribution points, + and OCSP server endpoints that will be encoded into issued certificates. + You can update any of the values at any time without affecting the other + existing values. To remove the values, simply use a blank string as the + parameter. +
+ +
Method
+
POST
+ +
URL
+
`/pki/config/urls`
+ +
Parameters
+
+
    +
  • + issuing_certificates + optional + The URL values for the Issuing Certificate field. +
    • +
  • + crl_distribution_points + optional + The URL values for the CRL Distribution Points field. +
    • +
  • + ocsp_servers + optional + The URL values for the OCSP Servers field. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+
+ +### /pki/crl(/pem) +#### GET + +
+
Description
+
+ Retrieves the current CRL *in raw DER-encoded form*. This endpoint + is suitable for usage in the CRL Distribution Points extension in a + CA certificate. This is a bare endpoint that does not return a + standard Vault data structure. If `/pem` is added to the endpoint, + the CRL is returned in PEM format. +

This is an unauthenticated endpoint. +
+ +
Method
+
GET
+ +
URL
+
`/pki/crl(/pem)`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ``` + + ``` + +
+
+ +### /pki/crl/rotate +#### GET + +
+
Description
+
+ This endpoint forces a rotation of the CRL. This can be used + by administrators to cut the size of the CRL if it contains + a number of certificates that have now expired, but has + not been rotated due to no further certificates being revoked. +
+ +
Method
+
GET
+ +
URL
+
`/pki/crl/rotate`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "data": { + "success": true + } + } + ``` + +
+
+ +### /pki/intermediate/generate +#### POST + +
+
Description
+
+ Generates a new private key and a CSR for signing. If using Vault as a + root, and for many other CAs, the various parameters on the final + certificate are set at signing time and may or may not honor the parameters + set here. _This will overwrite any previously existing CA private key._ If + the path ends with `exported`, the private key will be returned in the + response; if it is `internal` the private key will not be returned and + *cannot be retrieved later*.

This is mostly meant as a helper + function, and not all possible parameters that can be set in a CSR are + supported. +
+ +
Method
+
POST
+ +
URL
+
`/pki/intermediate/generate/[exported|internal]`
+ +
Parameters
+
+
    +
  • + common_name + required + The requested CN for the certificate. +
    • +
  • + alt_names + optional + Requested Subject Alternative Names, in a comma-delimited list. These + can be host names or email addresses; they will be parsed into their + respective fields. +
    • +
  • + ip_sans + optional + Requested IP Subject Alternative Names, in a comma-delimited list. +
    • +
  • + format + optional + Format for returned data. Can be `pem`, `der`, or `pem_bundle`; + defaults to `pem`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `csr` field will contain the private key (if + exported) and CSR, concatenated. +
    • +
  • + key_type + optional + Desired key type; must be `rsa` or `ec`. Defaults to `rsa`. +
    • +
  • + key_bits + optional + The number of bits to use. Defaults to `2048`. Must be changed to a + valid value if the `key_type` is `ec`. +
    • +
  • + exclude_cn_from_sans + optional + If set, the given `common_name` will not be included in DNS or Email + Subject Alternate Names (as appropriate). Useful if the CN is not a + hostname or email address, but is instead some human-readable + identifier. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "lease_id": "", + "renewable": false, + "lease_duration": 21600, + "data": { + "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE REQUEST-----\n", + "private_key": "-----BEGIN RSA PRIVATE KEY-----\\nMIIEpAIBAAKCAQEAwsANtGz9gS3o5SwTSlOG1l-----END RSA PRIVATE KEY-----", + "private_key_type": "rsa" + }, + "warnings": null, + "auth": null + } + ``` + +
+
+ +### /pki/intermediate/set-signed +#### POST + +
+
Description
+
+ Allows submitting the signed CA certificate corresponding to a private key generated via `/pki/intermediate/generate`. The certificate should be submitted in PEM format; see the documentation for `/pki/config/ca` for some hints on submitting. +
+ +
Method
+
POST
+ +
URL
+
`/pki/intermediate/set-signed`
+ +
Parameters
+
+
    +
  • + certificate + required + The certificate in PEM format. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+
+ +### /pki/issue/ +#### POST + +
+
Description
+
+ Generates a new set of credentials (private key and certificate) based on + the role named in the endpoint. The issuing CA certificate is returned as + well, so that only the root CA need be in a client's trust store.

*The private key is _not_ stored. If you do not save the private + key, you will need to request a new certificate.* +
+ +
Method
+
POST
+ +
URL
+
`/pki/issue/`
+ +
Parameters
+
+
    +
  • + common_name + required + The requested CN for the certificate. If the CN is allowed by role + policy, it will be issued. +
    • +
  • + alt_names + optional + Requested Subject Alternative Names, in a comma-delimited list. These + can be host names or email addresses; they will be parsed into their + respective fields. If any requested names do not match role policy, the + entire request will be denied. +
    • +
  • + ip_sans + optional + Requested IP Subject Alternative Names, in a comma-delimited list. Only + valid if the role allows IP SANs (which is the default). +
    • +
  • + 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. +
    • +
  • + format + optional + Format for returned data. Can be `pem`, `der`, or `pem_bundle`; + defaults to `pem`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the private key and + certificate, concatenated; if the issuing CA is not a Vault-derived + self-signed root, this will be included as well. +
    • +
  • + exclude_cn_from_sans + optional + If set, the given `common_name` will not be included in DNS or Email + Subject Alternate Names (as appropriate). Useful if the CN is not a + hostname or email address, but is instead some human-readable + identifier. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "lease_id": "pki/issue/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", + "renewable": false, + "lease_duration": 21600, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], + "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAnVHfwoKsUG1GDVyWB1AFroaKl2ImMBO8EnvGLRrmobIkQvh+\n...\nQN351pgTphi6nlCkGPzkDuwvtxSxiCWXQcaxrHAL7MiJpPzkIBq1\n-----END RSA PRIVATE KEY-----\n", + "private_key_type": "rsa", + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "warnings": "", + "auth": null + } + ``` + +
+
+ +### /pki/revoke +#### POST + +
+
Description
+
+ Revokes a certificate using its serial number. This is an + alternative option to the standard method of revoking + using Vault lease IDs. A successful revocation will + rotate the CRL. +
+ +
Method
+
POST
+ +
URL
+
`/pki/revoke`
+ +
Parameters
+
+
    +
  • + serial_number + required + The serial number of the certificate to revoke, in + hyphen-separated or colon-separated octal. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "data": { + "revocation_time": 1433269787 + } + } + ``` +
+
+ +### /pki/roles/ +#### POST + +
+
Description
+
+ Creates or updates the role definition. Note that the + `allowed_domains`, `allow_subdomains`, and + `allow_any_name` attributes are additive; between them nearly and across + multiple roles nearly any issuing policy can be accommodated. + `server_flag`, `client_flag`, and `code_signing_flag` are additive as well. + If a client requests a certificate that is not allowed by the CN policy in + the role, the request is denied. +
+ +
Method
+
POST
+ +
URL
+
`/pki/roles/`
+ +
Parameters
+
+
    +
  • + ttl + optional + 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 + optional + 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. +
    • +
  • + allow_localhost + optional + If set, clients can request certificates for `localhost` as one of the + requested common names. This is useful for testing and to allow clients + on a single host to talk securely. Defaults to true. +
    • +
  • + allowed_domains + optional + Designates the domains of the role, provided as a comma-separated list. + This is used with the `allow_bare_domains` and `allow_subdomains` + options. There is no default. +
    • +
  • + allow_bare_domains + optional + If set, clients can request certificates matching the value of the + actual domains themselves; e.g. if a configured domain set with + `allowed_domains` is `example.com`, this allows clients to actually + request a certificate containing the name `example.com` as one of the + DNS values on the final certificate. In some scenarios, this can be + considered a security risk. Defaults to false. +
    • +
  • + allow_subdomains + optional + If set, clients can request certificates with CNs that are subdomains + of the CNs allowed by the other role options. _This includes wildcard + subdomains._ For example, an `allowed_domains` value of + `example.com` with this option set to true will allow `foo.example.com` + and `bar.example.com` as well as `*.example.com`. This is redundant + when using the `allow_any_name` option. Defaults to `false`. +
    • +
  • + allow_any_name + optional + If set, clients can request any CN. Useful in some circumstances, but + make sure you understand whether it is appropriate for your + installation before enabling it. Defaults to `false`. +
    • +
  • + enforce_hostnames + optional + If set, only valid host names are allowed for CNs, DNS SANs, and the + host part of email addresses. Defaults to `true`. +
    • +
  • + allow_ip_sans + optional + If set, clients can request IP Subject Alternative Names. No + authorization checking is performed except to verify that the given + values are valid IP addresses. Defaults to `true`. +
  • + server_flag + optional + If set, certificates are flagged for server use. Defaults to `true`. +
    • +
  • + client_flag + optional + If set, certificates are flagged for client use. Defaults to `true`. +
    • +
  • + code_signing_flag + optional + If set, certificates are flagged for code signing use. Defaults to + `false`. +
    • +
  • + email_protection_flag + optional + If set, certificates are flagged for email protection use. Defaults to + `false`. +
    • +
  • + key_type + optional + The type of key to generate for generated private + keys. Currently, `rsa` and `ec` are supported. + Defaults to `rsa`. +
    • +
  • + key_bits + optional + The number of bits to use for the generated keys. + Defaults to `2048`; this will need to be changed for + `ec` keys. See https://golang.org/pkg/crypto/elliptic/#Curve + for an overview of allowed bit lengths for `ec`. +
    • +
  • + key_usage + optional + This sets the allowed key usage constraint on issued certificates. This + is a comma-separated string; valid values can be found at + https://golang.org/pkg/crypto/x509/#KeyUsage -- simply drop the + `KeyUsage` part of the value. Values are not case-sensitive. To specify + no key usage constraints, set this to an empty string. Defaults to + `DigitalSignature,KeyAgreement,KeyEncipherment`. +
    • +
  • + use_csr_common_name + optional + If set, when used with the CSR signing endpoint, the common name in the + CSR will be used instead of taken from the JSON data. This does `not` + include any requested SANs in the CSR; use `use_csr_sans` for that. + Defaults to `true`. +
    • +
  • + use_csr_sans + optional + If set, when used with the CSR signing endpoint, the subject alternate + names in the CSR will be used instead of taken from the JSON data. This + does `not` include the common name in the CSR; use + `use_csr_common_name` for that. Defaults to `true`. +
    • +
  • + allow_token_displayname + optional + If set, the display name of the token used when requesting a + certificate will be considered to be a valid host name by the role. + Normal verification behavior applies with respect to subdomains and + wildcards. +
    • +
  • + ou + optional + This sets the OU (OrganizationalUnit) values in the subject field of + issued certificates. This is a comma-separated string. +
    • +
  • + organization + optional + This sets the O (Organization) values in the subject field of issued + certificates. This is a comma-separated string. +
    • +
  • + generate_lease + optional + If set, certificates issued/signed against this role will have Vault + leases attached to them. Defaults to "false". Certificates can be added + to the CRL by `vault revoke ` when certificates are + associated with leases. It can also be done using the `pki/revoke` + endpoint. However, when lease generation is disabled, invoking + `pki/revoke` would be the only way to add the certificates to the CRL. + When large number of certificates are generated with long lifetimes, it + is recommended that lease generation be disabled, as large amount of + leases adversely affect the startup time of Vault. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+
+ +#### GET + +
+
Description
+
+ Queries the role definition. +
+ +
Method
+
GET
+ +
URL
+
`/pki/roles/`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "data": { + "allow_any_name": false, + "allow_ip_sans": true, + "allow_localhost": true, + "allow_subdomains": false, + "allowed_domains": "example.com,foobar.com", + "client_flag": true, + "code_signing_flag": false, + "key_bits": 2048, + "key_type": "rsa", + "ttl": "6h", + "max_ttl": "12h", + "server_flag": true + } + } + ``` + +
+
+ +#### LIST + +
+
Description
+
+ Returns a list of available roles. Only the role names are returned, not + any values. +
+ +
Method
+
LIST/GET
+ +
URL
+
`/pki/roles` (LIST) or `/pki/roles?list=true` (GET)
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false + } + ``` + +
+
+ +#### DELETE + +
+
Description
+
+ Deletes the role definition. Deleting a role does not revoke + certificates previously issued under this role. +
+ +
Method
+
DELETE
+ +
URL
+
`/pki/roles/`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ A `204` response code. +
+
+ +### /pki/root/generate +#### POST + +
+
Description
+
+ Generates a new self-signed CA certificate and private key. _This will + overwrite any previously-existing private key and certificate._ If the path + ends with `exported`, the private key will be returned in the response; if + it is `internal` the private key will not be returned and *cannot be + retrieved later*. Distribution points use the values set via `config/urls`. +

As with other issued certificates, Vault will automatically + revoke the generated root at the end of its lease period; the CA + certificate will sign its own CRL. +
+ +
Method
+
POST
+ +
URL
+
`/pki/root/generate/[exported|internal]`
+ +
Parameters
+
+
    +
  • + common_name + required + The requested CN for the certificate. +
    • +
  • + alt_names + optional + Requested Subject Alternative Names, in a comma-delimited list. These + can be host names or email addresses; they will be parsed into their + respective fields. +
    • +
  • + ip_sans + optional + Requested IP Subject Alternative Names, in a comma-delimited list. +
    • +
  • + ttl + optional + Requested Time To Live (after which the certificate will be expired). + This cannot be larger than the mount max (or, if not set, the system + max). +
    • +
  • + format + optional + Format for returned data. Can be `pem`, `der`, or `pem_bundle`; + defaults to `pem`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the private key (if + exported) and certificate, concatenated; if the issuing CA is not a + Vault-derived self-signed root, this will be included as well. +
    • +
  • + key_type + optional + Desired key type; must be `rsa` or `ec`. Defaults to `rsa`. +
    • +
  • + key_bits + optional + The number of bits to use. Defaults to `2048`. Must be changed to a + valid value if the `key_type` is `ec`. +
    • +
  • + max_path_length + optional + If set, the maximum path length to encode in the generated certificate. + Defaults to `-1`, which means no limit. unless the signing certificate + has a maximum path length set, in which case the path length is set to + one less than that of the signing certificate. A limit of `0` means a + literal path length of zero. +
    • +
  • + exclude_cn_from_sans + optional + If set, the given `common_name` will not be included in DNS or Email + Subject Alternate Names (as appropriate). Useful if the CN is not a + hostname or email address, but is instead some human-readable + identifier. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null + } + ``` + +
+
+ +### /pki/root/sign-intermediate +#### POST + +
+
Description
+
+ Uses the configured CA certificate to issue a certificate with appropriate + values for acting as an intermediate CA. Distribution points use the values + set via `config/urls`. Values set in the CSR are ignored unless + `use_csr_values` is set to true, in which case the values from the CSR are + used verbatim. +
+ +
Method
+
POST
+ +
URL
+
`/pki/root/sign-intermediate`
+ +
Parameters
+
+
    +
  • + csr + required + The PEM-encoded CSR. +
    • +
  • + common_name + required + The requested CN for the certificate. +
    • +
  • + alt_names + optional + Requested Subject Alternative Names, in a comma-delimited list. These + can be host names or email addresses; they will be parsed into their + respective fields. +
    • +
  • + ip_sans + optional + Requested IP Subject Alternative Names, in a comma-delimited list. +
    • +
  • + ttl + optional + Requested Time To Live (after which the certificate will be expired). + This cannot be larger than the mount max (or, if not set, the system + max). +
    • +
  • + format + optional + Format for returned data. Can be `pem`, `der`, or `pem_bundle`; + defaults to `pem`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the certificate and, + if the issuing CA is not a Vault-derived self-signed root, it will be + concatenated with the certificate. +
    • +
  • + max_path_length + optional + If set, the maximum path length to encode in the generated certificate. + Defaults to `-1`, which means no limit. unless the signing certificate + has a maximum path length set, in which case the path length is set to + one less than that of the signing certificate. A limit of `0` means a + literal path length of zero. +
    • +
  • + exclude_cn_from_sans + optional + If set, the given `common_name` will not be included in DNS or Email + Subject Alternate Names (as appropriate). Useful if the CN is not a + hostname or email address, but is instead some human-readable + identifier. +
    • +
  • + use_csr_values + optional + If set to `true`, then: 1) Subject information, including names and + alternate names, will be preserved from the CSR rather than using the + values provided in the other parameters to this path; 2) Any key usages + (for instance, non-repudiation) requested in the CSR will be added to + the basic set of key usages used for CA certs signed by this path; 3) + Extensions requested in the CSR will be copied into the issued + certificate. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], + "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null + } + ``` + +
+
+ +### /pki/sign/ +#### POST + +
+
Description
+
+ Signs a new certificate based upon the provided CSR and the supplied + parameters, subject to the restrictions contained in the role named in the + endpoint. The issuing CA certificate is returned as well, so that only the + root CA need be in a client's trust store. +
+ +
Method
+
POST
+ +
URL
+
`/pki/sign/`
+ +
Parameters
+
+
    +
  • + csr + required + The PEM-encoded CSR. +
    • +
  • + common_name + required + The requested CN for the certificate. If the CN is allowed by role + policy, it will be issued. +
    • +
  • + alt_names + optional + Requested Subject Alternative Names, in a comma-delimited list. These + can be host names or email addresses; they will be parsed into their + respective fields. If any requested names do not match role policy, the + entire request will be denied. +
    • +
  • + ip_sans + optional + Requested IP Subject Alternative Names, in a comma-delimited list. Only + valid if the role allows IP SANs (which is the default). +
    • +
  • + 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. +
    • +
  • + format + optional + Format for returned data. Can be `pem`, `der`, or `pem_bundle`; + defaults to `pem`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the certificate and, + if the issuing CA is not a Vault-derived self-signed root, it will be + concatenated with the certificate. +
    • +
  • + exclude_cn_from_sans + optional + If set, the given `common_name` will not be included in DNS or Email + Subject Alternate Names (as appropriate). Useful if the CN is not a + hostname or email address, but is instead some human-readable + identifier. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "lease_id": "pki/sign/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", + "renewable": false, + "lease_duration": 21600, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], + "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null + } + ``` + +
+
+ +### /pki/sign-verbatim +#### POST + +
+
Description
+
+ Signs a new certificate based upon the provided CSR. Values are taken + verbatim from the CSR; the _only_ restriction is that this endpoint will + refuse to issue an intermediate CA certificate (see the + `/pki/root/sign-intermediate` endpoint for that functionality.) _This is a + potentially dangerous endpoint and only highly trusted users should + have access._ +
+ +
Method
+
POST
+ +
URL
+
`/pki/sign-verbatim`
+ +
Parameters
+
+
    +
  • + csr + required + The PEM-encoded CSR. +
    • +
  • + ttl + optional + Requested Time To Live. Cannot be greater than the mount's `max_ttl` + value. If not provided, the mount's `ttl` value will be used, which + defaults to system values if not explicitly set. +
    • +
  • + format + optional + Format for returned data. Can be `pem`, `der`, or `pem_bundle`; + defaults to `pem`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the certificate and, + if the issuing CA is not a Vault-derived self-signed root, it will be + concatenated with the certificate. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "lease_id": "pki/sign-verbatim/7ad6cfa5-f04f-c62a-d477-f33210475d05", + "renewable": false, + "lease_duration": 21600, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"] + "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null + } + ``` + +
+
+ +### /pki/tidy +#### POST + +
+
Description
+
+ Allows tidying up the backend storage and/or CRL by removing certificates + that have expired and are past a certain buffer period beyond their + expiration time. +
+ +
Method
+
POST
+ +
URL
+
`/pki/tidy`
+ +
Parameters
+
+
    +
  • + tidy_cert_store + optional + Whether to tidy up the certificate store. Defaults to `false`. +
    • +
  • + tidy_revocation_list + optional + Whether to tidy up the revocation list (CRL). Defaults to `false`. +
    • +
  • + safety_buffer + optional + A duration (given as an integer number of seconds or a string; defaults + to `72h`) used as a safety buffer to ensure certificates are not + expunged prematurely; as an example, this can keep certificates from + being removed from the CRL that, due to clock skew, might still be + considered valid on other hosts. For a certificate to be expunged, the + time must be after the expiration time of the certificate (according to + the local clock) plus the duration of `safety_buffer`. +
    • +
+
+ +
Returns
+
+ 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/postgresql/index.html.md b/website/source/docs/http/secret/postgresql/index.html.md new file mode 100644 index 0000000000..6b032f6b1d --- /dev/null +++ b/website/source/docs/http/secret/postgresql/index.html.md @@ -0,0 +1,259 @@ +--- +layout: "http" +page_title: "PostgreSQL Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-postgresql" +description: |- + TODO +--- + +# PostgreSQL Secret Backend HTTP API + +This is the API documentation for the Vault PostgreSQL secret backend. For +general information about the usage and operation of the PostgreSQL backend, +please see the +[Vault PostgreSQL backend documentation](/docs/secrets/postgresql/index.html). + +This documentation assumes the PostgreSQL backend is mounted at the +`/postgresql` path in Vault. Since it is possible to mount secret backends at +any location, please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the connection string used to communicate with +PostgreSQL. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/postgresql/config/connection` | `204 (empty body)` | + +### Parameters + +- `connection_url` `(string: )` – Specifies the PostgreSQL connection + URL or PG-style string, for example `"user=foo host=bar"`. + +- `max_open_connections` `(int: 2)` – Specifies the maximum number of open + connections to the database. A negative value means unlimited. + +- `max_idle_connections` `(int: 0)` – Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If this is larger than + `max_open_connections` it will be reduced to be equal. + +- `verify_connection` `(bool: true)` – Specifies if the connection is verified + during initial configuration. + +### Sample Payload + +```json +{ + "connection_url": "postgresql://user:pass@localhost/my-db" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/postgresql/config/connection +``` + +## Configure Lease + +This configures the lease settings for generated credentials. If not configured, +leases default to 1 hour. This is a root protected endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/postgresql/config/lease` | `204 (empty body)` | + +### Parameters + +- `lease` `(string: )` – Specifies the lease value provided as a + string duration with time suffix. "h" (hour) is the largest suffix. + +- `lease_max` `(string: )` – Specifies the maximum lease value + provided as a string duration with time suffix. "h" (hour) is the largest + suffix. + +### Sample Payload + +```json +{ + "lease": "12h", + "lease_max": "24h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/postgresql/config/lease +``` + +## Create Role + +This endpoint creates or updates a role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/postgresql/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create. This + is specified as part of the URL. + +- `sql` `(string: )` – Specifies the SQL statements executed to create + and configure the role. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The '{{name}}', '{{password}}' + and '{{expiration}}' values will be substituted. + +- `revocation_sql` `(string: "")` – Specifies the SQL statements to be executed + to revoke a user. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The '{{name}}' value will be + substituted. + +### Sample Payload + +```json +{ + "sql": "CREATE USER WITH ROLE {{name}}" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/postgresql/roles/my-role +``` + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/postgresql/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/postgresql/roles/my-role +``` + +### Sample Response + +```json +{ + "data": { + "sql": "CREATE USER..." + } +} +``` + +## List Roles + +This endpoint returns a list of available roles. Only the role names are +returned, not any values. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/postgresql/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/postgresql/roles +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/postgresql/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/postgresql/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/postgresql/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/postgresql/creds/my-role +``` + +### Sample Response + +```json +{ + "data": { + "username": "root-1430158508-126", + "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" + } +} +``` diff --git a/website/source/docs/http/secret/rabbitmq/index.html.md b/website/source/docs/http/secret/rabbitmq/index.html.md new file mode 100644 index 0000000000..bf642f9116 --- /dev/null +++ b/website/source/docs/http/secret/rabbitmq/index.html.md @@ -0,0 +1,218 @@ +--- +layout: "http" +page_title: "RabbitMQ Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-rabbitmq" +description: |- + TODO +--- + +# RabbitMQ Secret Backend HTTP API + +This is the API documentation for the Vault RabbitMQ secret backend. For general +information about the usage and operation of the RabbitMQ backend, please see +the [Vault RabbitMQ backend documentation](/docs/secrets/rabbitmq/index.html). + +This documentation assumes the RabbitMQ backend is mounted at the `/rabbitmq` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the connection string used to communicate with +RabbitMQ. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/rabbitmq/config/connection` | `204 (empty body)` | + +### Parameters + +- `connection_uri` `(string: )` – Specifies the RabbitMQ connection + URI. + +- `username` `(string: )` – Specifies the RabbitMQ management + administrator username. + +- `password` `(string: )` – Specifies the RabbitMQ management + administrator password. + +- `verify_connection` `(bool: true)` – Specifies whether to verify connection + URI, username, and password. + +### Sample Payload + +```json +{ + "connection_uri": "https://...", + "username": "user", + "password": "password" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/rabbitmq/config/connection +``` + +## Configure Lease + +This endpoint configures the lease settings for generated credentials. This is +endpoint requires sudo privileges. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/rabbitmq/config/lease` | `204 (empty body)` | + +### Parameters + +- `ttl` `(int: 0)` – Specifies the lease ttl provided in seconds. + +- `max_ttl` `(int: 0)` – Specifies the maximum ttl provided in seconds. + +### Sample Payload + +```json +{ + "ttl": 1800, + "max_ttl": 3600 +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/rabbitmq/config/lease +``` + +## Create Role + +This endpoint creates or updates the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/rabbitmq/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create. This + is specified as part of the URL. + +- `tags` `(string: "")` – Specifies a comma-separated RabbitMQ management tags. + +- `vhost` `(string: "")` – Specifies a map of virtual hosts to + permissions. + +### Sample Payload + +```json +{ + "tags": "tag1,tag2", + "vhost": "{\"/\": {\"configure\":\".*\", \"write\":\".*\", \"read\": \".*\"}}" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/rabbitmq/roles/my-role +``` + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/rabbitmq/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/rabbitmq/roles/my-role +``` + +### Sample Response + +```json +{ + "data": { + "tags": "", + "vhost": "{\"/\": {\"configure\":\".*\", \"write\":\".*\", \"read\": \".*\"}}" + } +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/rabbitmq/roles/:namer` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/rabbitmq/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/rabbitmq/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/rabbitmq/creds/my-role +``` + +### Sample Response + +```json +{ + "data": { + "username": "root-4b95bf47-281d-dcb5-8a60-9594f8056092", + "password": "e1b6c159-ca63-4c6a-3886-6639eae06c30" + } +} +``` diff --git a/website/source/docs/http/secret/ssh/index.html.md b/website/source/docs/http/secret/ssh/index.html.md new file mode 100644 index 0000000000..df530de10b --- /dev/null +++ b/website/source/docs/http/secret/ssh/index.html.md @@ -0,0 +1,861 @@ +--- +layout: "http" +page_title: "SSH Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-ssh" +description: |- + TODO +--- + +# SSH Secret Backend HTTP API + +This is the API documentation for the Vault SSH secret backend. For general +information about the usage and operation of the SSH backend, please see the +[Vault SSH backend documentation](/docs/secrets/ssh/index.html). + +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 + +
+
Description
+
+ Creates or updates a named key. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/keys/`
+ +
Parameters
+
+
    +
  • + key + required + (String) + SSH private key with appropriate privileges on remote hosts. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+ +#### DELETE + +
+
Description
+
+ Deletes a named key. +
+ +
Method
+
DELETE
+ +
URL
+
`/ssh/keys/`
+ +
Parameters
+
None
+ +
Returns
+
+ A `204` response code. +
+ +### /ssh/roles/ +#### POST + +
+
Description
+
+ Creates or updates a named role. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/roles/`
+ +
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. + + 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. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+ +#### GET + +
+
Description
+
+ Queries a named role. +
+ +
Method
+
GET
+ +
URL
+
`/ssh/roles/`
+ +
Parameters
+
None
+ +
Returns
+
Note: these are examples only. For a dynamic key role: + +```json +{ + "admin_user": "username", + "cidr_list": "x.x.x.x/y", + "default_user": "username", + "key": "", + "key_type": "dynamic", + "port": 22 +} +``` + +
+ +
For an OTP role: + +```json +{ + "cidr_list": "x.x.x.x/y", + "default_user": "username", + "key_type": "otp", + "port": 22 +} +``` +
+
For a CA role: + +```json +{ + "allow_bare_domains": false, + "allow_host_certificates": true, + "allow_subdomains": false, + "allow_user_certificates": true, + "allowed_critical_options": "", + "allowed_extensions": "", + "default_critical_options": {}, + "default_extensions": {}, + "max_ttl": "768h", + "ttl": "4h" +} +``` +
+ +#### LIST + +
+
Description
+
+ Returns a list of available roles. Only the role names are returned, not + any values. +
+ +
Method
+
LIST/GET
+ +
URL
+
`/ssh/roles` (LIST) or `/ssh/roles?list=true` (GET)
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```json + { + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false + } + ``` + +
+
+ +#### DELETE + +
+
Description
+
+ Deletes a named role. +
+ +
Method
+
DELETE
+ +
URL
+
`/ssh/roles/`
+ +
Parameters
+
None
+ +
Returns
+
+ A `204` response code. +
+ +### /ssh/config/zeroaddress + +#### GET + +
+
Description
+
+ Returns the list of configured zero-address roles. +
+ +
Method
+
GET
+ +
URL
+
`/ssh/config/zeroaddress`
+ +
Parameters
+
None
+ +
Returns
+
+ +```json +{ + "lease_id":"", + "renewable":false, + "lease_duration":0, + "data":{ + "roles":[ + "otp_key_role" + ] + }, + "warnings":null, + "auth":null +} +``` + +
+ +#### POST + +
+
Description
+
+ Configures zero-address roles. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/config/zeroaddress`
+ +
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. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+ +#### DELETE + +
+
Description
+
+ Deletes the zero-address roles configuration. +
+ +
Method
+
DELETE
+ +
URL
+
`/ssh/config/zeroaddress`
+ +
Parameters
+
None
+ +
Returns
+
+ A `204` response code. +
+ + +### /ssh/creds/ +#### POST + +
+
Description
+
+ Creates credentials for a specific username and IP with the + parameters defined in the given role. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/creds/`
+ +
Parameters
+
+
    +
  • + username + optional + (String) + Username on the remote host. +
    • +
  • + ip + required + (String) + IP of the remote host. +
    • +
+
+ +
Returns
+
For a dynamic key role: + +```json +{ + "lease_id": "", + "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 + }, + "warnings": null, + "auth": null +} +``` + +
+ +
For an OTP role: + +```json +{ + "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 +} +``` +
+ + +### /ssh/lookup +#### POST + +
+
Description
+
+ Lists all of the roles with which the given IP is associated. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/lookup`
+ +
Parameters
+
+
    +
  • + ip + required + (String) + IP of the remote host. +
    • +
+
+ +
Returns
+
An array of roles as a secret structure. + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "roles": ["fe6f61b7-7e4a-46a6-b2c8-0d530b8513df", "6d6411fd-f622-ea0a-7e2c-989a745cbbb2"] + }, + "warnings": null, + "auth": null +} +``` +
+ +### /ssh/verify +#### POST + +
+
Description
+
+ Verifies if the given OTP is valid. This is an unauthenticated + endpoint. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/verify`
+ +
Parameters
+
+
    +
  • + otp + required + (String) + One-Time-Key that needs to be validated. +
    • +
+
+ +
Returns
+
A `200` response code for a valid OTP. + +```json +{ + "lease_id":"", + "renewable":false, + "lease_duration":0, + "data":{ + "ip":"127.0.0.1", + "username":"rajanadar" + }, + "warnings":null, + "auth":null +} +``` + +
+ +
A `400` BadRequest response code with 'OTP not found' message, for an invalid OTP.
+ +### /ssh/config/ca +#### POST + +
+
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._

+
+ +
Method
+
POST
+ +
URL
+
`/ssh/config/ca`
+ +
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. +
    • +
+
+ +
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 + } + ``` +
+
+ +#### GET + +
+
Description
+
+ Reads the configured/generated public key. +
+ +
Method
+
GET
+ +
URL
+
`/ssh/config/ca`
+ +
Parameters
+
None
+ +
Returns
+
+ ```json + { + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "public_key": "ssh-rsa AAAAHHNzaC1y...\n" + }, + "warnings": null + } + ``` +
+
+ +### /ssh/sign +#### POST + +
+
Description
+
+ Signs an SSH public key based on the supplied parameters, subject to the + restrictions contained in the role named in the endpoint. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/sign/`
+ +
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 +
    • +
+
+ +
Returns
+
+ + ```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 + } + ``` + +
+
+======= +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 diff --git a/website/source/docs/http/secret/transit/index.html.md b/website/source/docs/http/secret/transit/index.html.md new file mode 100644 index 0000000000..00b3a65c8a --- /dev/null +++ b/website/source/docs/http/secret/transit/index.html.md @@ -0,0 +1,859 @@ +--- +layout: "http" +page_title: "Transit Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-transit" +description: |- + TODO +--- + +# Transit Secret Backend HTTP API + +This is the API documentation for the Vault Transit secret backend. For general +information about the usage and operation of the Transit backend, please see the +[Vault Transit backend documentation](/docs/secrets/transit/index.html). + +This documentation assumes the Transit backend is mounted at the `/transit` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Create Key + +This endpoint creates a new named encryption key of the specified type. The +values set here cannot be changed after key creation. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/keys/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + create. This is specified as part of the URL. + +- `convergent_encryption` `(bool: false)` – If enabled, the key will support + convergent encryption, where the same plaintext creates the same ciphertext. + This requires _derived_ to be set to `true`. When enabled, each + encryption(/decryption/rewrap/datakey) operation will derive a `nonce` value + rather than randomly generate it. Note that while this is useful for + particular situations, all nonce values used with a given context value **must + be unique** or it will compromise the security of your key, and the key space + for nonces is 96 bit -- not as large as the AES key itself. + +- `derived` `(bool: false)` – Specifies if key derivation kist be used. If + enabled, all encrypt/decrypt requests to this named key must provide a context + which is used for key derivation. + +- `exportable` `(bool: false)` – Specifies if the raw key is exportable. + +- `type` `(string: "aes256-gcm96")` – Specifies the type of key to create. The + currently-supported types are: + + - `aes256-gcm96` – AES-256 wrapped with GCM using a 12-byte nonce size (symmetric) + - `ecdsa-p256` – ECDSA using the P-256 elliptic curve (asymmetric) + +### Sample Payload + +```json +{ + "type": "ecdsa-p256", + "derived": true +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/keys/my-key +``` + +## Read Key + +This endpoint returns information about a named encryption key. The `keys` +object shows the creation time of each key version; the values are not the keys +themselves. Depending on the type of key, different information may be returned, +e.g. an asymmetric key will return its public key in a standard format for the +type. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/transit/keys/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + read. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/transit/keys/my-key +``` + +### Sample Response + +```json +{ + "data": { + "type": "aes256-gcm96", + "deletion_allowed": false, + "derived": false, + "exportable": false, + "keys": { + "1": 1442851412 + }, + "min_decryption_version": 0, + "name": "foo", + "supports_encryption": true, + "supports_decryption": true, + "supports_derivation": true, + "supports_signing": false + } +} +``` + +## List Keys + +This endpoint returns a list of keys. Only the key names are returned (not the +actual keys themselves). + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/transit/keys` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/transit/keys +``` + +### Sample Response + +```json +{ + "data": { + "keys": ["foo", "bar"] + }, + "lease_duration": 0, + "lease_id": "", + "renewable": false +} +``` + +## Delete Key + +This endpoint deletes a named encryption key. It will no longer be possible to +decrypt any data encrypted with the named key. Because this is a potentially +catastrophic operation, the `deletion_allowed` tunable must be set in the key's +`/config` endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/transit/keys/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + delete. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/transit/keys/my-key +``` + +#### Update Key Configuration + +This endpoint allows tuning configuration values for a given key. (These values +are returned during a read operation on the named key.) + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/keys/:name/config` | `204 (empty body)` | + +### Parameters + +- `min_decryption_version` `(int: 0)` – Specifies the minimum version of + ciphertext allowed to be decrypted. Adjusting this as part of a key rotation + policy can prevent old copies of ciphertext from being decrypted, should they + fall into the wrong hands. For signatures, this value controls the minimum + version of signature that can be verified against. For HMACs, this controls + the minimum version of a key allowed to be used as the key for the HMAC + function. + +- `deletion_allowed` `(bool: false)`- Specifies if the key is allowed to be + deleted. + +### Sample Payload + +```json +{ + "deletion_allowed": true +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/keys/my-key/config +``` + +## Rotate Key + +This endpoint rotates the version of the named key. After rotation, new +plaintext requests will be encrypted with the new version of the key. To upgrade +ciphertext to be encrypted with the latest version of the key, use the `rewrap` +endpoint. This is only supported with keys that support encryption and +decryption operations. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/keys/:name/rotate` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/transit/keys/my-key/rotate +``` + +## Read Key + +This endpoint returns the named key. The `keys` object shows the value of the +key for each version. If `version` is specified, the specific version will be +returned. If `latest` is provided as the version, the current key will be +provided. Depending on the type of key, different information may be returned. +The key must be exportable to support this operation and the version must still +be valid. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/transit/export/:key_type/:name(/:version)` | `200 application/json` | + +### Parameters + +- `key_type` `(string: )` – Specifies the type of the key to export. + This is specified as part of the URL. Valid values are: + + - `encryption-key` + - `signing-key` + - `hmac-key` + +- `name` `(string: )` – Specifies the name of the key to read + information about. This is specified as part of the URL. + +- `version` `(int: "")` – Specifies the version of the key to read. If omitted, + all versions of the key will be returned. This is specified as part of the + URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/transit/export/encryption-key/my-key/1 +``` + +### Sample Response + +```json +{ + "data": { + "name": "foo", + "keys": { + "1": "eyXYGHbTmugUJn6EtYD/yVEoF6pCxm4R/cMEutUm3MY=", + "2": "Euzymqx6iXjS3/NuGKDCiM2Ev6wdhnU+rBiKnJ7YpHE=" + } + } +} +``` + +## Encrypt Data + +This endpoint encrypts the provided plaintext using the named key. Currently, +this only supports symmetric keys. This path supports the `create` and `update` +policy capabilities as follows: if the user has the `create` capability for this +endpoint in their policies, and the key does not exist, it will be upserted with +default values (whether the key requires derivation depends on whether the +context parameter is empty or not). If the user only has `update` capability and +the key does not exist, an error will be returned. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/encrypt/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + encrypt against. This is specified as part of the URL. + +- `plaintext` `(string: )` – Specifies **base64 encoded** plaintext to + be encoded. + +- `context` `(string: "")` – Specifies the **base64 encoded** context for key + derivation. This is required if key derivation is enabled for this key. + +- `nonce` `(string: "")` – Specifies the **base64 encoded** nonce value. This + must be provided if convergent encryption is enabled for this key and the key + was generated with Vault 0.6.1. Not required for keys created in 0.6.2+. The + value must be exactly 96 bits (12 bytes) long and the user must ensure that + for any given context (and thus, any given encryption key) this nonce value is + **never reused**. + +- `batch_input` `(array: nil)` – Specifies a list of items to be + encrypted in a single batch. When this parameter is set, if the parameters + 'plaintext', 'context' and 'nonce' are also set, they will be ignored. The + format for the input is: + + ```json + [ + { + "context": "c2FtcGxlY29udGV4dA==", + "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA==" + }, + { + "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", + "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA==" + }, + ] + ``` + +- `type` `(string: "aes256-gcm96")` –This parameter is required when encryption + key is expected to be created. When performing an upsert operation, the type + of key to create. Currently, "aes256-gcm96" (symmetric) is the only type + supported. + +- `convergent_encryption` `(string: "")` – This parameter will only be used when + a key is expected to be created. Whether to support convergent encryption. + This is only supported when using a key with key derivation enabled and will + require all requests to carry both a context and 96-bit (12-byte) nonce. The + given nonce will be used in place of a randomly generated nonce. As a result, + when the same context and nonce are supplied, the same ciphertext is + generated. It is _very important_ when using this mode that you ensure that + all nonces are unique for a given context. Failing to do so will severely + impact the ciphertext's security. + +### Sample Payload + +```json +{ + "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA==" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/encrypt/my-key +``` + +### Sample Response + +```json +{ + "data": { + "ciphertext": "vault:v1:abcdefgh" + } +} +``` + +## Decrypt Data + +This endpoint decrypts the provided ciphertext using the named key. Currently, +this only supports symmetric keys. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/decrypt/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + decrypt against. This is specified as part of the URL. + +- `ciphertext` `(string: )` – Specifies the ciphertext to decrypt. + +- `context` `(string: "")` – Specifies the **base64 encoded** context for key + derivation. This is required if key derivation is enabled. + +- `nonce` `(string: "")` – Specifies a base64 encoded nonce value used during + encryption. Must be provided if convergent encryption is enabled for this key + and the key was generated with Vault 0.6.1. Not required for keys created in + 0.6.2+. + +- `batch_input` `(array: nil)` – Specifies a list of items to be + decrypted in a single batch. When this parameter is set, if the parameters + 'ciphertext', 'context' and 'nonce' are also set, they will be ignored. Format + for the input goes like this: + + ```json + [ + { + "context": "c2FtcGxlY29udGV4dA==", + "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI=" + }, + { + "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", + "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" + }, + ] + ``` + +### Sample Payload + +```json +{ + "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/decrypt/my-key +``` + +### Sample Response + +```json +{ + "data": { + "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=" + } +} +``` + +## Rewrap Data + +This endpoint rewrapw the provided ciphertext using the latest version of the +named key. Because this never returns plaintext, it is possible to delegate this +functionality to untrusted users or scripts. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/rewrap/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + re-encrypt against. This is specified as part of the URL. + +- `ciphertext` `(string: )` – Specifies the ciphertext to re-encrypt. + +- `context` `(string: "")` – Specifies the **base64 encoded** context for key + derivation. This is required if key derivation is enabled. + +- `nonce` `(string: "")` – Specifies a base64 encoded nonce value used during + encryption. Must be provided if convergent encryption is enabled for this key + and the key was generated with Vault 0.6.1. Not required for keys created in + 0.6.2+. + +- `batch_input` `(array: nil)` – Specifies a list of items to be + decrypted in a single batch. When this parameter is set, if the parameters + 'ciphertext', 'context' and 'nonce' are also set, they will be ignored. Format + for the input goes like this: + + ```json + [ + { + "context": "c2FtcGxlY29udGV4dA==", + "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI=" + }, + { + "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", + "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" + }, + ] + ``` + +### Sample Payload + +```json +{ + "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/rewrap/my-key +``` + +### Sample Response + +```json +{ + "data": { + "ciphertext": "vault:v2:abcdefgh" + } +} +``` + +## Generate Data Key + +This endpoint generates a new high-entropy key and the value encrypted with the +named key. Optionally return the plaintext of the key as well. Whether plaintext +is returned depends on the path; as a result, you can use Vault ACL policies to +control whether a user is allowed to retrieve the plaintext value of a key. This +is useful if you want an untrusted user or operation to generate keys that are +then made available to trusted users. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/datakey/:type/:name` | `200 application/json` | + +### Parameters + +- `type` `(string: )` – Specifies the type of key to generate. If + `plaintext`, the plaintext key will be returned along with the ciphertext. If + `wrapped`, only the ciphertext value will be returned. This is specified as + part of the URL. + +- `name` `(string: )` – Specifies the name of the encryption key to + re-encrypt against. This is specified as part of the URL. + +- `context` `(string: "")` – Specifies the key derivation context, provided as a + base64-encoded string. This must be provided if derivation is enabled. + +- `nonce` `(string: "")` – Specifies a nonce value, provided as base64 encoded. + Must be provided if convergent encryption is enabled for this key and the key + was generated with Vault 0.6.1. Not required for keys created in 0.6.2+. The + value must be exactly 96 bits (12 bytes) long and the user must ensure that + for any given context (and thus, any given encryption key) this nonce value is + **never reused**. + +- `bits` `(int: 256)` – Specifies the number of bits in the desired key. Can be + 128, 256, or 512. + +### Sample Payload + +```json +{ + "context": "Ab3==" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/datakey/plaintext/my-key +``` + +### Sample Response + +```json +{ + "data": { + "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=", + "ciphertext": "vault:v1:abcdefgh" + } +} +``` + +## Generate Random Bytes + +This endpoint returns high-quality random bytes of the specified length. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/random(/:bytes)` | `200 application/json` | + +### Parameters + +- `bytes` `(int: 32)` – Specifies the number of bytes to return. This value can + be specified either in the request body, or as a part of the URL. + +- `format` `(string: "base64")` – Specifies the output encoding. Valid options + are `hex` or `base64`. + +### Sample Payload + +```json +{ + "format": "hex" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/random/164 +``` + +### Sample Response + +```json +{ + "data": { + "random_bytes": "dGhlIHF1aWNrIGJyb3duIGZveAo=" + } +} +``` + +## Hash Data + +This endpoint returns the cryptographic hash of given data using the specified +algorithm. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/hash(/:algorithm)` | `200 application/json` | + +### Parameters + +- `algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This + can also be specified as part of the URL. Currently-supported algorithms are: + + - `sha2-224` + - `sha2-256` + - `sha2-384` + - `sha2-512` + +- `input` `(string: )` – Specifies the **base64 encoded** input data. + +- `format` `(string: "hex")` – Specifies the output encoding. This can be either + `hex` or `base64`. + +### Sample Payload + +```json +{ + "input": "adba32==" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/hash/sha2-512 +``` + +### Sample Response + +```json +{ + "data": { + "sum": "dGhlIHF1aWNrIGJyb3duIGZveAo=" + } +} +``` + +## Generate HMAC with Key + +This endpoint returns the digest of given data using the specified hash +algorithm and the named key. The key can be of any type supported by `transit`; +the raw key will be marshaled into bytes to be used for the HMAC function. If +the key is of a type that supports rotation, the latest (current) version will +be used. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/hmac/:name(/:algorithm)` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + generate hmac against. This is specified as part of the URL. + +- `algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This + can also be specified as part of the URL. Currently-supported algorithms are: + + - `sha2-224` + - `sha2-256` + - `sha2-384` + - `sha2-512` + +- `input` `(string: )` – Specifies the **base64 encoded** input data. + +- `format` `(string: "hex")` – Specifies the output encoding. This can be either + `hex` or `base64`. + +### Sample Payload + +```json +{ + "input": "adba32==" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/hmac/my-key/sha2-512 +``` + +### Sample Response + +```json +{ + "data": { + "hmac": "dGhlIHF1aWNrIGJyb3duIGZveAo=" + } +} +``` + +## Sign Data with Key + +This endpoint returns the cryptographic signature of the given data using the +named key and the specified hash algorithm. The key must be of a type that +supports signing. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/sign/:name(/:algorithm)` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + generate hmac against. This is specified as part of the URL. + +- `algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This + can also be specified as part of the URL. Currently-supported algorithms are: + + - `sha2-224` + - `sha2-256` + - `sha2-384` + - `sha2-512` + +- `input` `(string: )` – Specifies the **base64 encoded** input data. + +- `format` `(string: "hex")` – Specifies the output encoding. This can be either + `hex` or `base64`. + +### Sample Payload + +```json +{ + "input": "adba32==" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/sign/my-key/sha2-512 +``` + +### Sample Response + +```json +{ + "data": { + "signature": "vault:v1:MEUCIQCyb869d7KWuA0hBM9b5NJrmWzMW3/pT+0XYCM9VmGR+QIgWWF6ufi4OS2xo1eS2V5IeJQfsi59qeMWtgX0LipxEHI=" + } +} +``` + +## Verify Data with Key + +This endpoint returns whether the provided signature is valid for the given +data. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/verify/:name(/:algorithm)` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + generate hmac against. This is specified as part of the URL. + +- `algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This + can also be specified as part of the URL. Currently-supported algorithms are: + + - `sha2-224` + - `sha2-256` + - `sha2-384` + - `sha2-512` + +- `input` `(string: )` – Specifies the **base64 encoded** input data. + +- `format` `(string: "hex")` – Specifies the output encoding. This can be either + `hex` or `base64`. + +- `signature` `(string: "")` – Specifies the signature output from the + `/transit/sign` function. Either this must be supplied or `hmac` must be + supplied. + +- `hmac` `(string: "")` – Specifies the signature output from the + `/transit/hmac` function. Either this must be supplied or `signature` must be + supplied. + +### Sample Payload + +```json +{ + "input": "abcd13==", + "signature": "vault:v1:MEUCIQCyb869d7KWuA..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/verify/my-key/sha2-512 +``` + +### Sample Response + +```json +{ + "data": { + "valid": true + } +} +``` diff --git a/website/source/docs/secrets/aws/index.html.md b/website/source/docs/secrets/aws/index.html.md index c352d3da90..d3bc154fd6 100644 --- a/website/source/docs/secrets/aws/index.html.md +++ b/website/source/docs/secrets/aws/index.html.md @@ -45,7 +45,7 @@ The following parameters are required: credentials. - `region` the AWS region for API calls. -Note: the client uses the official AWS SDK and will use environment variable or IAM +Note: the client uses the official AWS SDK and will use environment variable or IAM role-provided credentials if available. The next step is to configure a role. A role is a logical name that maps @@ -159,7 +159,7 @@ Here is an example IAM policy that would grant these permissions: ``` Note that this policy example is unrelated to the policy you wrote to `aws/roles/deploy`. -This policy example should be applied to the IAM user (or role) associated with +This policy example should be applied to the IAM user (or role) associated with the root credentials that you wrote to `aws/config/root`. You have to apply it yourself in IAM. The policy you wrote to `aws/roles/deploy` is the policy you want the AWS secret backend to apply to the temporary credentials it returns @@ -364,341 +364,6 @@ errors for exceeding the AWS limit of 32 characters on STS token names. ## API -### /aws/config/root -#### POST - -
-
Description
-
- Configures the root IAM credentials used. - If static credentials are not provided using - this endpoint, then the credentials will be retrieved from the - environment variables `AWS_ACCESS_KEY`, `AWS_SECRET_KEY` and `AWS_REGION` - respectively. If the credentials are still not found and if the - backend is configured on an EC2 instance with metadata querying - capabilities, the credentials are fetched automatically. -
- -
Method
-
POST
- -
URL
-
`/aws/config/root`
- -
Parameters
-
-
    -
  • - access_key - required - The AWS Access Key -
    • -
  • - secret_key - required - The AWS Secret Key -
    • -
  • - region - required - The AWS region for API calls -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /aws/config/lease -#### POST - -
-
Description
-
- Configures the lease settings for generated credentials. -
- -
Method
-
POST
- -
URL
-
`/aws/config/lease`
- -
Parameters
-
-
    -
  • - lease - required - The lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - lease_max - required - The maximum lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /aws/roles/ -#### POST - -
-
Description
-
- Creates or updates a named role. -
- -
Method
-
POST
- -
URL
-
`/aws/roles/`
- -
Parameters
-
-
    -
  • - policy - required (unless arn specified) - The IAM policy in JSON format. -
    • -
  • - arn - required (unless policy specified) - The full ARN reference to the desired existing policy -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries a named role. -
- -
Method
-
GET
- -
URL
-
`/aws/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- ```javascript - { - "data": { - "policy": "..." - } - } - ``` - ```javascript - { - "data": { - "arn": "..." - } - } - ``` -
-
- -#### DELETE - -
-
Description
-
- Deletes a named role. -
- -
Method
-
DELETE
- -
URL
-
`/aws/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -#### LIST - -
-
Description
-
- Returns a list of existing roles in the backend -
- -
Method
-
LIST/GET
- -
URL
-
`/aws/roles` (LIST) or `/aws/roles/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- ```javascript -{ - "auth": null, - "warnings": null, - "wrap_info": null, - "data": { - "keys": [ - "devrole", - "prodrole", - "testrole" - ] - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} - ``` -
-
- - -### /aws/creds/ -#### GET - -
-
Description
-
- Generates a dynamic IAM credential based on the named role. -
- -
Method
-
GET
- -
URL
-
`/aws/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- ```javascript - { - "data": { - "access_key": "...", - "secret_key": "...", - "security_token": null - } - } - ``` -
-
- - -### /aws/sts/ -#### GET - -
-
Description
-
- Generates a dynamic IAM credential with an STS token based on the named - role. The TTL will be 3600 seconds (one hour). -
- -
Method
-
GET
- -
URL
-
`/aws/sts/`
- -
Parameters
-
- None -
- -
Returns
-
- ```javascript - { - "data": { - "access_key": "...", - "secret_key": "...", - "security_token": "..." - } - } - ``` -
-
- -#### POST - -
-
Description
-
- Generates a dynamic IAM credential with an STS token based on the named - role and the given TTL (defaults to 3600 seconds, or one hour). -
- -
Method
-
POST
- -
URL
-
`/aws/sts/`
- -
Parameters
-
-
    -
  • - ttl - optional - The TTL to use for the STS token. -
    • -
-
- -
Returns
-
- ```javascript - { - "data": { - "access_key": "...", - "secret_key": "...", - "security_token": "..." - } - } - ``` -
-
+The AWS secret backend has a full HTTP API. Please see the +[AWS secret backend API](/docs/http/secret/aws/index.html) for more +details. diff --git a/website/source/docs/secrets/cassandra/index.html.md b/website/source/docs/secrets/cassandra/index.html.md index 08fd6ce7ad..0ac9dcbc69 100644 --- a/website/source/docs/secrets/cassandra/index.html.md +++ b/website/source/docs/secrets/cassandra/index.html.md @@ -94,262 +94,6 @@ subpath for interactive help output. ## API -### /cassandra/config/connection -#### POST - -
-
Description
-
- Configures the connection information used to communicate with Cassandra. - TLS works as follows:

-
    -
  • - • If `tls` is set to true, the connection will use TLS; this happens - automatically if `pem_bundle`, `pem_json`, or `insecure_tls` is set -
    • -
  • - • If `insecure_tls` is set to true, the connection will not perform - verification of the server certificate; this also sets `tls` to true -
    • -
  • - • If only `issuing_ca` is set in `pem_json`, or the only certificate in - `pem_bundle` is a CA certificate, the given CA certificate will be used - for server certificate verification; otherwise the system CA - certificates will be used -
    • -
  • - • If `certificate` and `private_key` are set in `pem_bundle` or - `pem_json`, client auth will be turned on for the connection -
    • -
- `pem_bundle` should be a PEM-concatenated bundle of a private key + client - certificate, an issuing CA certificate, or both. `pem_json` should contain - the same information; for convenience, the JSON format is the same as that - output by the issue command from the PKI backend. -
- -
Method
-
POST
- -
URL
-
`/cassandra/config/connection`
- -
Parameters
-
-
    -
  • - hosts - required - A set of comma-deliniated Cassandra hosts to connect to. -
    • -
  • - username - required - The username to use for superuser access. -
    • -
  • - password - required - The password corresponding to the given username. -
    • -
  • - tls - optional - Whether to use TLS when connecting to Cassandra. -
    • -
  • - insecure_tls - optional - Whether to skip verification of the server certificate when using TLS. -
    • -
  • - pem_bundle - optional - Concatenated PEM blocks containing a certificate and private key; - a certificate, private key, and issuing CA certificate; or just a CA - certificate. -
    • -
  • - pem_json - optional - JSON containing a certificate and private key; - a certificate, private key, and issuing CA certificate; or just a CA - certificate. For convenience format is the same as the output of the - `issue` command from the `pki` backend; see [the pki documentation](https://www.vaultproject.io/docs/secrets/pki/index.html). -
    • -
  • - protocol_version - optional - The CQL protocol version to use. Defaults to 2. -
    • -
  • - connect_timeout - optional - The connection timeout to use. Defaults to 5 seconds. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /cassandra/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. -
- -
Method
-
POST
- -
URL
-
`/cassandra/roles/`
- -
Parameters
-
-
    -
  • - creation_cql - optional - The CQL statements executed to create and configure the new user. Must - be a semicolon-separated string, a base64-encoded semicolon-separated - string, a serialized JSON string array, or a base64-encoded serialized - JSON string array. The '{{username}}' and '{{password}}' values will be - substituted; it is required that these parameters are in single quotes. - The default creates a non-superuser user with no authorization grants. -
    • -
  • - rollback_cql - optional - The CQL statements executed to attempt a rollback if an error is - encountered during user creation. The default is to delete the user. - Must be a semicolon-separated string, a base64-encoded - semicolon-separated string, a serialized JSON string array, or a - base64-encoded serialized JSON string array. The '{{username}}' and - '{{password}}' values will be substituted; it is required that these - parameters are in single quotes. -
    • -
  • - lease - optional - The lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - consistency - optional - The consistency level value provided as a string. Determines the - consistency level used for operations performed on the Cassandra - database. Defaults to a consistency level of Quorum. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/cassandra/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "creation_cql": "CREATE USER...", - "rollback_cql": "DROP USER...", - "lease": "12h", - "consistency": "Quorum" - } - } - ``` - -
-
- - -#### DELETE - -
-
Description
-
- Deletes the role definition. -
- -
Method
-
DELETE
- -
URL
-
`/cassandra/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /cassandra/creds/ -#### GET - -
-
Description
-
- Generates a new set of dynamic credentials based on the named role. -
- -
Method
-
GET
- -
URL
-
`/cassandra/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "username": "vault-root-1430158508-126", - "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" - } - } - ``` - -
-
+The Cassandra secret backend has a full HTTP API. Please see the +[Cassandra secret backend API](/docs/http/secret/cassandra/index.html) for more +details. diff --git a/website/source/docs/secrets/consul/index.html.md b/website/source/docs/secrets/consul/index.html.md index b1fd2c4fae..052f2cfb7f 100644 --- a/website/source/docs/secrets/consul/index.html.md +++ b/website/source/docs/secrets/consul/index.html.md @@ -98,184 +98,6 @@ Permission denied ## API -### /consul/config/access -#### POST - -
-
Description
-
- Configures the access information for Consul. -
- -
Method
-
POST
- -
URL
-
`/consul/config/access`
- -
Parameters
-
-
    -
  • - address - required - The address of the Consul instance, provided as host:port -
    • -
  • - scheme - optional - The URL scheme to use. Defaults to HTTP, as Consul does not expose HTTPS by default. -
    • -
  • - token - required - The Consul ACL token to use. Must be a management type token. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /consul/roles/ -#### POST - -
-
Description
-
- Creates or updates the Consul role definition. -
- -
Method
-
POST
- -
URL
-
`/consul/roles/`
- -
Parameters
-
-
    -
  • - policy - required - The base64 encoded Consul ACL policy. This is documented in [more - detail here](https://www.consul.io/docs/internals/acl.html). Required - unless the `token_type` is `management`. -
    • -
  • - token_type - optional - The type of token to create using this role: `client` or `management`. - If `management`, the `policy` parameter is not required. -
    • -
  • - lease - optional - The lease value provided as a string duration with time suffix. Hour is - the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries a Consul role definition. -
- -
Method
-
GET
- -
URL
-
`/consul/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "policy": "abcdef=", - "lease": "1h0m0s", - "token_type": "client" - } - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes a Consul role definition. -
- -
Method
-
DELETE
- -
URL
-
`/consul/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /consul/creds/ -#### GET - -
-
Description
-
- Generates a dynamic Consul token based on the role definition. -
- -
Method
-
GET
- -
URL
-
`/consul/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "token": "973a31ea-1ec4-c2de-0f63-623f477c2510" - } - } - ``` - -
-
+The Consul secret backend has a full HTTP API. Please see the +[Consul secret backend API](/docs/http/secret/consul/index.html) for more +details. diff --git a/website/source/docs/secrets/cubbyhole/index.html.md b/website/source/docs/secrets/cubbyhole/index.html.md index 860493ac2b..79d91f8b65 100644 --- a/website/source/docs/secrets/cubbyhole/index.html.md +++ b/website/source/docs/secrets/cubbyhole/index.html.md @@ -89,139 +89,6 @@ As expected, the value previously set is returned to us. ## API -#### GET - -
-
Description
-
- Retrieves the secret at the specified location. -
- -
Method
-
GET
- -
URL
-
`/cubbyhole/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "foo": "bar" - }, - "lease_duration": 0, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of secret entries at the specified location. Folders are - suffixed with `/`. The input must be a folder; list on a file will not - return a value. The values themselves are not accessible via this command. -
- -
Method
-
LIST/GET
- -
URL
-
`/cubbyhole/` (LIST) or `/cubbyhole/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- The example below shows output for a query path of `cubbyhole/` when there - are secrets at `cubbyhole/foo` and `cubbyhole/foo/bar`; note the difference - in the two entries. - - ```javascript - { - "auth": null, - "data": { - "keys": ["foo", "foo/"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### POST/PUT - -
-
Description
-
- Stores a secret at the specified location. -
- -
Method
-
POST/PUT
- -
URL
-
`/cubbyhole/`
- -
Parameters
-
-
    -
  • - (key) - optional - A key, paired with an associated value, to be held at the - given location. Multiple key/value pairs can be specified, - and all will be returned on a read operation. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### DELETE - -
-
Description
-
- Deletes the secret at the specified location. -
- -
Method
-
DELETE
- -
URL
-
`/cubbyhole/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
+The Cubbyhole secret backend has a full HTTP API. Please see the +[Cubbyhole secret backend API](/docs/http/secret/cubbyhole/index.html) for more +details. diff --git a/website/source/docs/secrets/generic/index.html.md b/website/source/docs/secrets/generic/index.html.md index 937b9ff31d..7c67a80472 100644 --- a/website/source/docs/secrets/generic/index.html.md +++ b/website/source/docs/secrets/generic/index.html.md @@ -70,145 +70,6 @@ seconds (one hour) as specified. ## API -#### GET - -
-
Description
-
- Retrieves the secret at the specified location. -
- -
Method
-
GET
- -
URL
-
`/secret/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "foo": "bar" - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of key names at the specified location. Folders are - suffixed with `/`. The input must be a folder; list on a file will not - return a value. Note that no policy-based filtering is performed on keys; - do not encode sensitive information in key names. The values themselves - are not accessible via this command. -
- -
Method
-
LIST/GET
- -
URL
-
`/secret/` (LIST) or `/secret/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- The example below shows output for a query path of `secret/` when there are - secrets at `secret/foo` and `secret/foo/bar`; note the difference in the two - entries. - - ```javascript - { - "auth": null, - "data": { - "keys": ["foo", "foo/"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### POST/PUT - -
-
Description
-
- Stores a secret at the specified location. If the value does not yet exist, - the calling token must have an ACL policy granting the `create` capability. - If the value already exists, the calling token must have an ACL policy - granting the `update` capability. -
- -
Method
-
POST/PUT
- -
URL
-
`/secret/`
- -
Parameters
-
-
    -
  • - (key) - optional - A key, paired with an associated value, to be held at the given - location. Multiple key/value pairs can be specified, and all will be - returned on a read operation. A key called `ttl` will trigger some - special behavior; see above for details. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### DELETE - -
-
Description
-
- Deletes the secret at the specified location. -
- -
Method
-
DELETE
- -
URL
-
`/secret/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
+The Generic secret backend has a full HTTP API. Please see the +[Generic secret backend API](/docs/http/secret/generic/index.html) for more +details. diff --git a/website/source/docs/secrets/mongodb/index.html.md b/website/source/docs/secrets/mongodb/index.html.md index 0406ea3b83..bd8dccca5a 100644 --- a/website/source/docs/secrets/mongodb/index.html.md +++ b/website/source/docs/secrets/mongodb/index.html.md @@ -120,368 +120,6 @@ applications are restricted in the credentials they are allowed to read. ## API -### /mongodb/config/connection -#### POST - -
-
Description
-
- Configures the standard connection string (URI) used to communicate with MongoDB. -
- -
Method
-
POST
- -
URL
-
`/mongodb/config/connection`
- -
Parameters
-
-
    -
  • - uri - required - The MongoDB standard connection string (URI) -
    • -
-
- -
-
    -
  • - verify_connection - optional - If set, uri is verified by actually connecting to the database. - Defaults to true. -
    • -
-
- -
Returns
-
- A `200` response code. -
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": null, - "wrap_info": null, - "warnings": [ - "Read access to this endpoint should be controlled via ACLs as it will return the connection URI as it is, including passwords, if any." - ], - "auth": null - } - ``` - -
-
- -#### GET - -
-
Description
-
- Queries the connection configuration. Access to this endpoint should be controlled via ACLs as it will return the - connection URI as it is, including passwords, if any. -
- -
Method
-
GET
- -
URL
-
`/mongodb/config/connection`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "uri": "mongodb://admin:Password!@mongodb.acme.com:27017/admin?ssl=true" - }, - "wrap_info": null, - "warnings": null, - "auth": null - } - ``` - -
-
- -### /mongodb/config/lease -#### POST - -
-
Description
-
- Configures the default lease TTL settings for credentials generated by the mongodb backend. -
- -
Method
-
POST
- -
URL
-
`/mongodb/config/lease`
- -
Parameters
-
-
    -
  • - ttl - optional - The ttl value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - max_ttl - optional - The maximum ttl value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the lease configuration. -
- -
Method
-
GET
- -
URL
-
`/mongodb/config/lease`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "max_ttl": 60, - "ttl": 60 - }, - "wrap_info": null, - "warnings": null, - "auth": null - } - ``` - -
-
- -### /mongodb/roles/\ -#### POST - -
-
Description
-
- Creates or updates a role definition. -
- -
Method
-
POST
- -
URL
-
`/mongodb/roles/`
- -
Parameters
-
-
    -
  • - db - required - The name of the database users should be created in for this role. -
    • -
  • - roles - optional - MongoDB roles to assign to the users generated for this role. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/mongodb/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "db": "foo", - "roles": "[\"readWrite\",{\"db\":\"bar\",\"role\":\"read\"}]" - }, - "wrap_info": null, - "warnings": null, - "auth": null - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/mongodb/roles` (LIST) or `/mongodb/roles/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "keys": [ - "dev", - "prod" - ] - }, - "wrap_info": null, - "warnings": null, - "auth": null - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes the role definition. -
- -
Method
-
DELETE
- -
URL
-
`/mongodb/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /mongodb/creds/ -#### GET - -
-
Description
-
- Generates a new set of dynamic credentials based on the named role. -
- -
Method
-
GET
- -
URL
-
`/mongodb/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "mongodb/creds/readonly/e64e79d8-9f56-e379-a7c5-373f9b4ee3d8", - "renewable": true, - "lease_duration": 3600, - "data": { - "db": "foo", - "password": "de0f7b50-d700-54e5-4e81-5c3724283999", - "username": "vault-token-b32098cb-7ff2-dcf5-83cd-d5887cedf81b" - }, - "wrap_info": null, - "warnings": null, - "auth": null - } - ``` - -
-
+The MongoDB secret backend has a full HTTP API. Please see the +[MongoDB secret backend API](/docs/http/secret/mongodb/index.html) for more +details. diff --git a/website/source/docs/secrets/mssql/index.html.md b/website/source/docs/secrets/mssql/index.html.md index b10d7c783a..79f40dfc46 100644 --- a/website/source/docs/secrets/mssql/index.html.md +++ b/website/source/docs/secrets/mssql/index.html.md @@ -110,301 +110,6 @@ allowed to read. ## API -### /mssql/config/connection -#### POST - -
-
Description
-
- Configures the connection DSN used to communicate with Sql Server. -
- -
Method
-
POST
- -
URL
-
`/mssql/config/connection`
- -
Parameters
-
-
    -
  • - connection_string - required - The MSSQL DSN -
    • -
-
-
-
    -
  • - max_open_connections - optional - Maximum number of open connections to the database. - Defaults to 2. -
    • -
-
-
-
    -
  • - verify_connection - optional - If set, connection_string is verified by actually connecting to the database. - Defaults to true. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /mssql/config/lease -#### POST - -
-
Description
-
- Configures the lease settings for generated credentials. -
- -
Method
-
POST
- -
URL
-
`/mssql/config/lease`
- -
Parameters
-
-
    -
  • - ttl - required - The ttl value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - max_ttl - required - The maximum ttl value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the lease configuration. -
- -
Method
-
GET
- -
URL
-
`/mssql/config/lease`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "max_ttl": "5h", - "ttl": "1h", - "ttl_max": "5h" - }, - "wrap_info": null, - "warnings": ["The field ttl_max is deprecated and will be removed in a future release. Use max_ttl instead."], - "auth": null - } - ``` - -
-
- -### /mssql/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. -
- -
Method
-
POST
- -
URL
-
`/mssql/roles/`
- -
Parameters
-
-
    -
  • - sql - required - The SQL statements executed to create and configure the role. The - '{{name}}' and '{{password}}' values will be substituted. Must be a - semicolon-separated string, a base64-encoded semicolon-separated - string, a serialized JSON string array, or a base64-encoded serialized - JSON string array. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/mssql/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "sql": "CREATE LOGIN..." - } - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/mssql/roles` (LIST) or `/mssql/roles/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes the role definition. -
- -
Method
-
DELETE
- -
URL
-
`/mssql/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /mssql/creds/ -#### GET - -
-
Description
-
- Generates a new set of dynamic credentials based on the named role. -
- -
Method
-
GET
- -
URL
-
`/mssql/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "username": "root-a147d529-e7d6-4a16-8930-4c3e72170b19", - "password": "ee202d0d-e4fd-4410-8d14-2a78c5c8cb76" - } - } - ``` - -
-
+The MSSQL secret backend has a full HTTP API. Please see the +[MSSQL secret backend API](/docs/http/secret/mssql/index.html) for more +details. diff --git a/website/source/docs/secrets/mysql/index.html.md b/website/source/docs/secrets/mysql/index.html.md index 0986dbb998..c169af73ba 100644 --- a/website/source/docs/secrets/mysql/index.html.md +++ b/website/source/docs/secrets/mysql/index.html.md @@ -109,7 +109,7 @@ allowed to read. Optionally, you may configure both the number of characters from the role name that are truncated to form the display name portion of the mysql username -interpolated into the `{{name}}` field: the default is 10. +interpolated into the `{{name}}` field: the default is 10. You may also configure the total number of characters allowed in the entire generated username (the sum of the display name and uuid portions); the @@ -119,309 +119,6 @@ the default on versions prior to that. ## API -### /mysql/config/connection -#### POST - -
-
Description
-
- Configures the connection DSN used to communicate with MySQL. -
- -
Method
-
POST
- -
URL
-
`/mysql/config/connection`
- -
Parameters
-
-
    -
  • - connection_url - required - The MySQL DSN -
    • -
-
-
-
    -
  • - value - optional -
    • -
-
-
-
    -
  • - max_open_connections - optional - Maximum number of open connections to the database. - Defaults to 2. -
    • -
-
-
-
    -
  • - max_idle_connections - optional - Maximum number of idle connections to the database. A zero uses the value of `max_open_connections` and a negative value disables idle connections. If larger than `max_open_connections` it will be reduced to be equal. -
    • -
-
-
-
    -
  • - verify_connection - optional - If set, connection_url is verified by actually connecting to the database. - Defaults to true. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /mysql/config/lease -#### POST - -
-
Description
-
- Configures the lease settings for generated credentials. - If not configured, leases default to 1 hour. This is a root - protected endpoint. -
- -
Method
-
POST
- -
URL
-
`/mysql/config/lease`
- -
Parameters
-
-
    -
  • - lease - required - The lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - lease_max - required - The maximum lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /mysql/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. -
- -
Method
-
POST
- -
URL
-
`/mysql/roles/`
- -
Parameters
-
-
    -
  • - sql - required - The SQL statements executed to create and configure a user. Must be a - semicolon-separated string, a base64-encoded semicolon-separated - string, a serialized JSON string array, or a base64-encoded serialized - JSON string array. The '{{name}}' and '{{password}}' values will be - substituted. -
    • -
  • - revocation_sql - optional - The SQL statements executed to revoke a user. Must be a - semicolon-separated string, a base64-encoded semicolon-separated - string, a serialized JSON string array, or a base64-encoded serialized - JSON string array. The '{{name}}' value will be substituted. -
    • -
  • - rolename_length - optional - Determines how many characters from the role name will be used - to form the mysql username interpolated into the '{{name}}' field - of the sql parameter. The default is 4. -
    • -
  • - displayname_length - optional - Determines how many characters from the token display name will be used - to form the mysql username interpolated into the '{{name}}' field - of the sql parameter. The default is 4. -
    • -
  • - username_length - optional - Determines the maximum total length in characters of the - mysql username interpolated into the '{{name}}' field - of the sql parameter. The default is 16. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/mysql/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "sql": "CREATE USER..." - } - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/mysql/roles` (LIST) or `/mysql/roles/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes the role definition. -
- -
Method
-
DELETE
- -
URL
-
`/mysql/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /mysql/creds/ -#### GET - -
-
Description
-
- Generates a new set of dynamic credentials based on the named role. -
- -
Method
-
GET
- -
URL
-
`/mysql/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "username": "user-role-aefa63", - "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" - } - } - ``` - -
-
- +The MySQL secret backend has a full HTTP API. Please see the +[MySQL secret backend API](/docs/http/secret/mysql/index.html) for more +details. diff --git a/website/source/docs/secrets/pki/index.html.md b/website/source/docs/secrets/pki/index.html.md index bc1f0a2d40..f5acdbda82 100644 --- a/website/source/docs/secrets/pki/index.html.md +++ b/website/source/docs/secrets/pki/index.html.md @@ -382,1435 +382,6 @@ subpath for interactive help output. ## API -### /pki/ca(/pem) -#### GET - -
-
Description
-
- Retrieves the CA certificate *in raw DER-encoded form*. This is a bare - endpoint that does not return a standard Vault data structure. If `/pem` is - added to the endpoint, the CA certificate is returned in PEM format.
-
This is an unauthenticated endpoint. -
- -
Method
-
GET
- -
URL
-
`/pki/ca(/pem)`
- -
Parameters
-
- None -
- -
Returns
-
- - ``` - - ``` - -
-
- -### /pki/ca_chain -#### GET - -
-
Description
-
- Retrieves the CA certificate chain, including the CA *in PEM format*. This - is a bare endpoint that does not return a standard Vault data structure. -

This is an unauthenticated endpoint. -
- -
Method
-
GET
- -
URL
-
`/pki/ca_chain`
- -
Parameters
-
- None -
- -
Returns
-
- - ``` - - ``` - -
-
- -### /pki/cert/ -#### GET - -
-
Description
-
- Retrieves one of a selection of certificates. Valid values: `ca` for the CA - certificate, `crl` for the current CRL, `ca_chain` for the CA trust chain - or a serial number in either hyphen-separated or colon-separated octal - format. This endpoint returns the certificate in PEM formatting in the - `certificate` key of the JSON object.

This is an unauthenticated endpoint. -
- -
Method
-
GET
- -
URL
-
`/pki/cert/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIGmDCCBYCgAwIBAgIHBzEB3fTzhTANBgkqhkiG9w0BAQsFADCBjDELMAkGA1UE\n..." - } - } - ... - ``` - -
-
- -### /pki/certs/ -#### LIST - -
-
Description
-
- Returns a list of the current certificates by serial number only. -
- -
Method
-
LIST/GET
- -
URL
-
`/pki/certs` (LIST) or `/pki/certs?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id":"", - "renewable":false, - "lease_duration":0, - "data":{ - "keys":[ - "17:67:16:b0:b9:45:58:c0:3a:29:e3:cb:d6:98:33:7a:a6:3b:66:c1", - "26:0f:76:93:73:cb:3f:a0:7a:ff:97:85:42:48:3a:aa:e5:96:03:21" - ] - }, - "wrap_info":null, - "warnings":null, - "auth":null - } - ... - ``` - -
-
- -### /pki/config/ca -#### POST - -
-
Description
-
- Allows submitting the CA information for the backend via a PEM file - containing the CA certificate and its private key, concatenated. Not needed - if you are generating a self-signed root certificate, and not used if you - have a signed intermediate CA certificate with a generated key (use the - `/pki/intermediate/set-signed` endpoint for that). _If you have already set - a certificate and key, they will be overridden._

The information - can be provided from a file via a `curl` command similar to the - following:
- - ```text - $ curl \ - -H "X-Vault-Token:06b9d..." \ - -X POST \ - --data "@cabundle.json" \ - http://127.0.0.1:8200/v1/pki/config/ca - ``` - - Note that if you provide the data through the HTTP API it must be - JSON-formatted, with newlines replaced with `\n`, like so: - - ```javascript - { - "pem_bundle": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END CERTIFICATE-----" - } - ``` -
- -
Method
-
POST
- -
URL
-
`/pki/config/ca`
- -
Parameters
-
-
    -
  • - pem_bundle - required - The key and certificate concatenated in PEM format. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /pki/config/crl -#### GET - -
-
Description
-
- Allows getting the duration for which the generated CRL should be marked - valid. -
- -
Method
-
GET
- -
URL
-
`/pki/config/crl`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "expiry": "72h" - }, - "auth": null - } - ``` - -
-
- -#### POST - -
-
Description
-
- Allows setting the duration for which the generated CRL should be marked - valid. -
- -
Method
-
POST
- -
URL
-
`/pki/config/crl`
- -
Parameters
-
-
    -
  • -
  • - expiry - required - The time until expiration. Defaults to `72h`. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /pki/config/urls - -#### GET - -
-
Description
-
- Fetch the URLs to be encoded in generated certificates. -
- -
Method
-
GET
- -
URL
-
`/pki/config/urls`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "issuing_certificates": [, ], - "crl_distribution_points": [, ], - "ocsp_servers": [, ], - }, - "auth": null - } - ``` - -
-
- -#### POST - -
-
Description
-
- Allows setting the issuing certificate endpoints, CRL distribution points, - and OCSP server endpoints that will be encoded into issued certificates. - You can update any of the values at any time without affecting the other - existing values. To remove the values, simply use a blank string as the - parameter. -
- -
Method
-
POST
- -
URL
-
`/pki/config/urls`
- -
Parameters
-
-
    -
  • - issuing_certificates - optional - The URL values for the Issuing Certificate field. -
    • -
  • - crl_distribution_points - optional - The URL values for the CRL Distribution Points field. -
    • -
  • - ocsp_servers - optional - The URL values for the OCSP Servers field. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /pki/crl(/pem) -#### GET - -
-
Description
-
- Retrieves the current CRL *in raw DER-encoded form*. This endpoint - is suitable for usage in the CRL Distribution Points extension in a - CA certificate. This is a bare endpoint that does not return a - standard Vault data structure. If `/pem` is added to the endpoint, - the CRL is returned in PEM format. -

This is an unauthenticated endpoint. -
- -
Method
-
GET
- -
URL
-
`/pki/crl(/pem)`
- -
Parameters
-
- None -
- -
Returns
-
- - ``` - - ``` - -
-
- -### /pki/crl/rotate -#### GET - -
-
Description
-
- This endpoint forces a rotation of the CRL. This can be used - by administrators to cut the size of the CRL if it contains - a number of certificates that have now expired, but has - not been rotated due to no further certificates being revoked. -
- -
Method
-
GET
- -
URL
-
`/pki/crl/rotate`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "success": true - } - } - ``` - -
-
- -### /pki/intermediate/generate -#### POST - -
-
Description
-
- Generates a new private key and a CSR for signing. If using Vault as a - root, and for many other CAs, the various parameters on the final - certificate are set at signing time and may or may not honor the parameters - set here. _This will overwrite any previously existing CA private key._ If - the path ends with `exported`, the private key will be returned in the - response; if it is `internal` the private key will not be returned and - *cannot be retrieved later*.

This is mostly meant as a helper - function, and not all possible parameters that can be set in a CSR are - supported. -
- -
Method
-
POST
- -
URL
-
`/pki/intermediate/generate/[exported|internal]`
- -
Parameters
-
-
    -
  • - common_name - required - The requested CN for the certificate. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `csr` field will contain the private key (if - exported) and CSR, concatenated. -
    • -
  • - key_type - optional - Desired key type; must be `rsa` or `ec`. Defaults to `rsa`. -
    • -
  • - key_bits - optional - The number of bits to use. Defaults to `2048`. Must be changed to a - valid value if the `key_type` is `ec`. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 21600, - "data": { - "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE REQUEST-----\n", - "private_key": "-----BEGIN RSA PRIVATE KEY-----\\nMIIEpAIBAAKCAQEAwsANtGz9gS3o5SwTSlOG1l-----END RSA PRIVATE KEY-----", - "private_key_type": "rsa" - }, - "warnings": null, - "auth": null - } - ``` - -
-
- -### /pki/intermediate/set-signed -#### POST - -
-
Description
-
- Allows submitting the signed CA certificate corresponding to a private key generated via `/pki/intermediate/generate`. The certificate should be submitted in PEM format; see the documentation for `/pki/config/ca` for some hints on submitting. -
- -
Method
-
POST
- -
URL
-
`/pki/intermediate/set-signed`
- -
Parameters
-
-
    -
  • - certificate - required - The certificate in PEM format. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /pki/issue/ -#### POST - -
-
Description
-
- Generates a new set of credentials (private key and certificate) based on - the role named in the endpoint. The issuing CA certificate is returned as - well, so that only the root CA need be in a client's trust store.

*The private key is _not_ stored. If you do not save the private - key, you will need to request a new certificate.* -
- -
Method
-
POST
- -
URL
-
`/pki/issue/`
- -
Parameters
-
-
    -
  • - common_name - required - The requested CN for the certificate. If the CN is allowed by role - policy, it will be issued. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. If any requested names do not match role policy, the - entire request will be denied. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. Only - valid if the role allows IP SANs (which is the default). -
    • -
  • - 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. -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the private key and - certificate, concatenated; if the issuing CA is not a Vault-derived - self-signed root, this will be included as well. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "pki/issue/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", - "renewable": false, - "lease_duration": 21600, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", - "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], - "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAnVHfwoKsUG1GDVyWB1AFroaKl2ImMBO8EnvGLRrmobIkQvh+\n...\nQN351pgTphi6nlCkGPzkDuwvtxSxiCWXQcaxrHAL7MiJpPzkIBq1\n-----END RSA PRIVATE KEY-----\n", - "private_key_type": "rsa", - "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "warnings": "", - "auth": null - } - ``` - -
-
- -### /pki/revoke -#### POST - -
-
Description
-
- Revokes a certificate using its serial number. This is an - alternative option to the standard method of revoking - using Vault lease IDs. A successful revocation will - rotate the CRL. -
- -
Method
-
POST
- -
URL
-
`/pki/revoke`
- -
Parameters
-
-
    -
  • - serial_number - required - The serial number of the certificate to revoke, in - hyphen-separated or colon-separated octal. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "revocation_time": 1433269787 - } - } - ``` -
-
- -### /pki/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. Note that the - `allowed_domains`, `allow_subdomains`, and - `allow_any_name` attributes are additive; between them nearly and across - multiple roles nearly any issuing policy can be accommodated. - `server_flag`, `client_flag`, and `code_signing_flag` are additive as well. - If a client requests a certificate that is not allowed by the CN policy in - the role, the request is denied. -
- -
Method
-
POST
- -
URL
-
`/pki/roles/`
- -
Parameters
-
-
    -
  • - ttl - optional - 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 - optional - 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. -
    • -
  • - allow_localhost - optional - If set, clients can request certificates for `localhost` as one of the - requested common names. This is useful for testing and to allow clients - on a single host to talk securely. Defaults to true. -
    • -
  • - allowed_domains - optional - Designates the domains of the role, provided as a comma-separated list. - This is used with the `allow_bare_domains` and `allow_subdomains` - options. There is no default. -
    • -
  • - allow_bare_domains - optional - If set, clients can request certificates matching the value of the - actual domains themselves; e.g. if a configured domain set with - `allowed_domains` is `example.com`, this allows clients to actually - request a certificate containing the name `example.com` as one of the - DNS values on the final certificate. In some scenarios, this can be - considered a security risk. Defaults to false. -
    • -
  • - allow_subdomains - optional - If set, clients can request certificates with CNs that are subdomains - of the CNs allowed by the other role options. _This includes wildcard - subdomains._ For example, an `allowed_domains` value of - `example.com` with this option set to true will allow `foo.example.com` - and `bar.example.com` as well as `*.example.com`. This is redundant - when using the `allow_any_name` option. Defaults to `false`. -
    • -
  • - allow_any_name - optional - If set, clients can request any CN. Useful in some circumstances, but - make sure you understand whether it is appropriate for your - installation before enabling it. Defaults to `false`. -
    • -
  • - enforce_hostnames - optional - If set, only valid host names are allowed for CNs, DNS SANs, and the - host part of email addresses. Defaults to `true`. -
    • -
  • - allow_ip_sans - optional - If set, clients can request IP Subject Alternative Names. No - authorization checking is performed except to verify that the given - values are valid IP addresses. Defaults to `true`. -
  • - server_flag - optional - If set, certificates are flagged for server use. Defaults to `true`. -
    • -
  • - client_flag - optional - If set, certificates are flagged for client use. Defaults to `true`. -
    • -
  • - code_signing_flag - optional - If set, certificates are flagged for code signing use. Defaults to - `false`. -
    • -
  • - email_protection_flag - optional - If set, certificates are flagged for email protection use. Defaults to - `false`. -
    • -
  • - key_type - optional - The type of key to generate for generated private - keys. Currently, `rsa` and `ec` are supported. - Defaults to `rsa`. -
    • -
  • - key_bits - optional - The number of bits to use for the generated keys. - Defaults to `2048`; this will need to be changed for - `ec` keys. See https://golang.org/pkg/crypto/elliptic/#Curve - for an overview of allowed bit lengths for `ec`. -
    • -
  • - key_usage - optional - This sets the allowed key usage constraint on issued certificates. This - is a comma-separated string; valid values can be found at - https://golang.org/pkg/crypto/x509/#KeyUsage -- simply drop the - `KeyUsage` part of the value. Values are not case-sensitive. To specify - no key usage constraints, set this to an empty string. Defaults to - `DigitalSignature,KeyAgreement,KeyEncipherment`. -
    • -
  • - use_csr_common_name - optional - If set, when used with the CSR signing endpoint, the common name in the - CSR will be used instead of taken from the JSON data. This does `not` - include any requested SANs in the CSR; use `use_csr_sans` for that. - Defaults to `true`. -
    • -
  • - use_csr_sans - optional - If set, when used with the CSR signing endpoint, the subject alternate - names in the CSR will be used instead of taken from the JSON data. This - does `not` include the common name in the CSR; use - `use_csr_common_name` for that. Defaults to `true`. -
    • -
  • - allow_token_displayname - optional - If set, the display name of the token used when requesting a - certificate will be considered to be a valid host name by the role. - Normal verification behavior applies with respect to subdomains and - wildcards. -
    • -
  • - ou - optional - This sets the OU (OrganizationalUnit) values in the subject field of - issued certificates. This is a comma-separated string. -
    • -
  • - organization - optional - This sets the O (Organization) values in the subject field of issued - certificates. This is a comma-separated string. -
    • -
  • - generate_lease - optional - If set, certificates issued/signed against this role will have Vault - leases attached to them. Defaults to "false". Certificates can be added - to the CRL by `vault revoke ` when certificates are - associated with leases. It can also be done using the `pki/revoke` - endpoint. However, when lease generation is disabled, invoking - `pki/revoke` would be the only way to add the certificates to the CRL. - When large number of certificates are generated with long lifetimes, it - is recommended that lease generation be disabled, as large amount of - leases adversely affect the startup time of Vault. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/pki/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "allow_any_name": false, - "allow_ip_sans": true, - "allow_localhost": true, - "allow_subdomains": false, - "allowed_domains": "example.com,foobar.com", - "client_flag": true, - "code_signing_flag": false, - "key_bits": 2048, - "key_type": "rsa", - "ttl": "6h", - "max_ttl": "12h", - "server_flag": true - } - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/pki/roles` (LIST) or `/pki/roles?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes the role definition. Deleting a role does not revoke - certificates previously issued under this role. -
- -
Method
-
DELETE
- -
URL
-
`/pki/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /pki/root/generate -#### POST - -
-
Description
-
- Generates a new self-signed CA certificate and private key. _This will - overwrite any previously-existing private key and certificate._ If the path - ends with `exported`, the private key will be returned in the response; if - it is `internal` the private key will not be returned and *cannot be - retrieved later*. Distribution points use the values set via `config/urls`. -

As with other issued certificates, Vault will automatically - revoke the generated root at the end of its lease period; the CA - certificate will sign its own CRL. -
- -
Method
-
POST
- -
URL
-
`/pki/root/generate/[exported|internal]`
- -
Parameters
-
-
    -
  • - common_name - required - The requested CN for the certificate. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. -
    • -
  • - ttl - optional - Requested Time To Live (after which the certificate will be expired). - This cannot be larger than the mount max (or, if not set, the system - max). -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the private key (if - exported) and certificate, concatenated; if the issuing CA is not a - Vault-derived self-signed root, this will be included as well. -
    • -
  • - key_type - optional - Desired key type; must be `rsa` or `ec`. Defaults to `rsa`. -
    • -
  • - key_bits - optional - The number of bits to use. Defaults to `2048`. Must be changed to a - valid value if the `key_type` is `ec`. -
    • -
  • - max_path_length - optional - If set, the maximum path length to encode in the generated certificate. - Defaults to `-1`, which means no limit. unless the signing certificate - has a maximum path length set, in which case the path length is set to - one less than that of the signing certificate. A limit of `0` means a - literal path length of zero. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "lease_duration": 0, - "renewable": false, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "auth": null - } - ``` - -
-
- -### /pki/root/sign-intermediate -#### POST - -
-
Description
-
- Uses the configured CA certificate to issue a certificate with appropriate - values for acting as an intermediate CA. Distribution points use the values - set via `config/urls`. Values set in the CSR are ignored unless - `use_csr_values` is set to true, in which case the values from the CSR are - used verbatim. -
- -
Method
-
POST
- -
URL
-
`/pki/root/sign-intermediate`
- -
Parameters
-
-
    -
  • - csr - required - The PEM-encoded CSR. -
    • -
  • - common_name - required - The requested CN for the certificate. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. -
    • -
  • - ttl - optional - Requested Time To Live (after which the certificate will be expired). - This cannot be larger than the mount max (or, if not set, the system - max). -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the certificate and, - if the issuing CA is not a Vault-derived self-signed root, it will be - concatenated with the certificate. -
    • -
  • - max_path_length - optional - If set, the maximum path length to encode in the generated certificate. - Defaults to `-1`, which means no limit. unless the signing certificate - has a maximum path length set, in which case the path length is set to - one less than that of the signing certificate. A limit of `0` means a - literal path length of zero. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
  • - use_csr_values - optional - If set to `true`, then: 1) Subject information, including names and - alternate names, will be preserved from the CSR rather than using the - values provided in the other parameters to this path; 2) Any key usages - (for instance, non-repudiation) requested in the CSR will be added to - the basic set of key usages used for CA certs signed by this path; 3) - Extensions requested in the CSR will be copied into the issued - certificate. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", - "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], - "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "auth": null - } - ``` - -
-
- -### /pki/sign/ -#### POST - -
-
Description
-
- Signs a new certificate based upon the provided CSR and the supplied - parameters, subject to the restrictions contained in the role named in the - endpoint. The issuing CA certificate is returned as well, so that only the - root CA need be in a client's trust store. -
- -
Method
-
POST
- -
URL
-
`/pki/sign/`
- -
Parameters
-
-
    -
  • - csr - required - The PEM-encoded CSR. -
    • -
  • - common_name - required - The requested CN for the certificate. If the CN is allowed by role - policy, it will be issued. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. If any requested names do not match role policy, the - entire request will be denied. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. Only - valid if the role allows IP SANs (which is the default). -
    • -
  • - 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. -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the certificate and, - if the issuing CA is not a Vault-derived self-signed root, it will be - concatenated with the certificate. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "pki/sign/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", - "renewable": false, - "lease_duration": 21600, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", - "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], - "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "auth": null - } - ``` - -
-
- -### /pki/sign-verbatim -#### POST - -
-
Description
-
- Signs a new certificate based upon the provided CSR. Values are taken - verbatim from the CSR; the _only_ restriction is that this endpoint will - refuse to issue an intermediate CA certificate (see the - `/pki/root/sign-intermediate` endpoint for that functionality.) _This is a - potentially dangerous endpoint and only highly trusted users should - have access._ -
- -
Method
-
POST
- -
URL
-
`/pki/sign-verbatim`
- -
Parameters
-
-
    -
  • - csr - required - The PEM-encoded CSR. -
    • -
  • - ttl - optional - Requested Time To Live. Cannot be greater than the mount's `max_ttl` - value. If not provided, the mount's `ttl` value will be used, which - defaults to system values if not explicitly set. -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the certificate and, - if the issuing CA is not a Vault-derived self-signed root, it will be - concatenated with the certificate. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "pki/sign-verbatim/7ad6cfa5-f04f-c62a-d477-f33210475d05", - "renewable": false, - "lease_duration": 21600, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", - "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"] - "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "auth": null - } - ``` - -
-
- -### /pki/tidy -#### POST - -
-
Description
-
- Allows tidying up the backend storage and/or CRL by removing certificates - that have expired and are past a certain buffer period beyond their - expiration time. -
- -
Method
-
POST
- -
URL
-
`/pki/tidy`
- -
Parameters
-
-
    -
  • - tidy_cert_store - optional - Whether to tidy up the certificate store. Defaults to `false`. -
    • -
  • - tidy_revocation_list - optional - Whether to tidy up the revocation list (CRL). Defaults to `false`. -
    • -
  • - safety_buffer - optional - A duration (given as an integer number of seconds or a string; defaults - to `72h`) used as a safety buffer to ensure certificates are not - expunged prematurely; as an example, this can keep certificates from - being removed from the CRL that, due to clock skew, might still be - considered valid on other hosts. For a certificate to be expunged, the - time must be after the expiration time of the certificate (according to - the local clock) plus the duration of `safety_buffer`. -
    • -
-
- -
Returns
-
- 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. diff --git a/website/source/docs/secrets/postgresql/index.html.md b/website/source/docs/secrets/postgresql/index.html.md index 49d4f8661f..d696e3f544 100644 --- a/website/source/docs/secrets/postgresql/index.html.md +++ b/website/source/docs/secrets/postgresql/index.html.md @@ -109,290 +109,6 @@ subpath for interactive help output. ## API -### /postgresql/config/connection -#### POST - -
-
Description
-
- Configures the connection string used to communicate with PostgreSQL. -
- -
Method
-
POST
- -
URL
-
`/postgresql/config/connection`
- -
Parameters
-
-
    -
  • - connection_url - required - The PostgreSQL connection URL or PG style string. e.g. "user=foo host=bar" -
    • -
-
-
-
    -
  • - value - optional - The PostgreSQL connection URL or PG style string. e.g. "user=foo host=bar". Use `connection_url` instead. -
    • -
-
-
-
    -
  • - max_open_connections - optional - Maximum number of open connections to the database. A zero uses the - default value of 2 and a negative value means unlimited. -
    • -
-
-
-
    - max_idle_connections - optional - Maximum number of idle connections to the database. A zero uses the - value of `max_open_connections` and a negative value disables idle - connections. If larger than `max_open_connections` it will be reduced - to be equal. -
-
-
-
    - verify_connection - optional - If set, connection_url is verified by actually connecting to the database. - Defaults to true. -
-
- -
Returns
-
- A `204` response code. -
-
- -### /postgresql/config/lease -#### POST - -
-
Description
-
- Configures the lease settings for generated credentials. - If not configured, leases default to 1 hour. This is a root - protected endpoint. -
- -
Method
-
POST
- -
URL
-
`/postgresql/config/lease`
- -
Parameters
-
-
    -
  • - lease - required - The lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - lease_max - required - The maximum lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /postgresql/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. -
- -
Method
-
POST
- -
URL
-
`/postgresql/roles/`
- -
Parameters
-
-
    -
  • - sql - required - The SQL statements executed to create and configure the role. Must be - a semicolon-separated string, a base64-encoded semicolon-separated - string, a serialized JSON string array, or a base64-encoded serialized - JSON string array. The '{{name}}', '{{password}}' and '{{expiration}}' - values will be substituted. -
    • -
-
    -
  • - revocation_sql - optional - SQL statements to be executed to revoke a user. Must be a semicolon-separated - string, a base64-encoded semicolon-separated string, a serialized JSON string - array, or a base64-encoded serialized JSON string array. The '{{name}}' value - will be substituted. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/postgresql/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "sql": "CREATE USER..." - } - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/postgresql/roles` (LIST) or `/postgresql/roles/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes the role definition. -
- -
Method
-
DELETE
- -
URL
-
`/postgresql/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /postgresql/creds/ -#### GET - -
-
Description
-
- Generates a new set of dynamic credentials based on the named role. -
- -
Method
-
GET
- -
URL
-
`/postgresql/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "username": "root-1430158508-126", - "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" - } - } - ``` - -
-
- +The PostgreSQL secret backend has a full HTTP API. Please see the +[PostgreSQL secret backend API](/docs/http/secret/postgresql/index.html) for more +details. diff --git a/website/source/docs/secrets/rabbitmq/index.html.md b/website/source/docs/secrets/rabbitmq/index.html.md index ebc36b477e..5afa3f6ae8 100644 --- a/website/source/docs/secrets/rabbitmq/index.html.md +++ b/website/source/docs/secrets/rabbitmq/index.html.md @@ -110,219 +110,6 @@ subpath for interactive help output. ## API -### /rabbitmq/config/connection -#### POST - -
-
Description
-
- Configures the connection string used to communicate with RabbitMQ. -
- -
Method
-
POST
- -
URL
-
`/rabbitmq/config/connection`
- -
Parameters
-
-
    -
  • - connection_uri - required - The RabbitMQ management connection URI. -
    • -
  • - username - required - The RabbitMQ management administrator username. -
    • -
  • - password - required - The RabbitMQ management administrator password. -
    • -
  • - verify_connection - optional - Whether to verify connection URI, username, and password. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /rabbitmq/config/lease -#### POST - -
-
Description
-
- Configures the lease settings for generated credentials. This is a root - protected endpoint. -
- -
Method
-
POST
- -
URL
-
`/rabbitmq/config/lease`
- -
Parameters
-
-
    -
  • - ttl - optional - The lease ttl provided in seconds. -
    • -
  • - max_ttl - optional - The maximum ttl provided in seconds. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /rabbitmq/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. -
- -
Method
-
POST
- -
URL
-
`/rabbitmq/roles/`
- -
Parameters
-
-
    -
  • - tags - optional - Comma-separated RabbitMQ management tags. -
    • -
  • - vhost - optional - A map of virtual hosts to permissions. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/rabbitmq/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "tags": "", - "vhost": "{\"/\": {\"configure\:".*", \"write\:".*", \"read\": \".*\"}}" - } - } - ``` - -
-
- - -#### DELETE - -
-
Description
-
- Deletes the role definition. -
- -
Method
-
DELETE
- -
URL
-
`/rabbitmq/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /rabbitmq/creds/ -#### GET - -
-
Description
-
- Generates a new set of dynamic credentials based on the named role. -
- -
Method
-
GET
- -
URL
-
`/rabbitmq/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "username": "root-4b95bf47-281d-dcb5-8a60-9594f8056092", - "password": "e1b6c159-ca63-4c6a-3886-6639eae06c30" - } - } - ``` - -
-
+The RabbitMQ secret backend has a full HTTP API. Please see the +[RabbitMQ secret backend API](/docs/http/secret/rabbitmq/index.html) for more +details. diff --git a/website/source/docs/secrets/ssh/index.html.md b/website/source/docs/secrets/ssh/index.html.md index 6de7ba27f1..43a2b85aed 100644 --- a/website/source/docs/secrets/ssh/index.html.md +++ b/website/source/docs/secrets/ssh/index.html.md @@ -329,7 +329,7 @@ sign an SSH public key, we simply write to the `sign` end point with that role name: Vault is now configured to create and manage SSH certificates! ```text -$ cat dummy.pub | vault write ssh/sign/example public_key=- +$ cat dummy.pub | vault write ssh/sign/example public_key=- Key Value --- ----- lease_id ssh/sign/example/3c3740ee-6066-55c0-4a5d-82a544a474a3 @@ -352,850 +352,6 @@ username@:~$ ---------------------------------------------------- ## API -### /ssh/keys/ -#### POST - -
-
Description
-
- Creates or updates a named key. -
- -
Method
-
POST
- -
URL
-
`/ssh/keys/`
- -
Parameters
-
-
    -
  • - key - required - (String) - SSH private key with appropriate privileges on remote hosts. -
    • -
-
- -
Returns
-
- A `204` response code. -
- -#### DELETE - -
-
Description
-
- Deletes a named key. -
- -
Method
-
DELETE
- -
URL
-
`/ssh/keys/`
- -
Parameters
-
None
- -
Returns
-
- A `204` response code. -
- -### /ssh/roles/ -#### POST - -
-
Description
-
- Creates or updates a named role. -
- -
Method
-
POST
- -
URL
-
`/ssh/roles/`
- -
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. - - 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. -
    • -
  • - allow_user_key_ids - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If true, users can override the key ID for a signed certificate with the "key_id" field. - When false, the key ID will always be the token display name. - The key ID is logged by the SSH server and can be useful for auditing. -
    • -
-
- -
Returns
-
- A `204` response code. -
- -#### GET - -
-
Description
-
- Queries a named role. -
- -
Method
-
GET
- -
URL
-
`/ssh/roles/`
- -
Parameters
-
None
- -
Returns
-
Note: these are examples only. For a dynamic key role: - -```json -{ - "admin_user": "username", - "cidr_list": "x.x.x.x/y", - "default_user": "username", - "key": "", - "key_type": "dynamic", - "port": 22 -} -``` - -
- -
For an OTP role: - -```json -{ - "cidr_list": "x.x.x.x/y", - "default_user": "username", - "key_type": "otp", - "port": 22 -} -``` -
-
For a CA role: - -```json -{ - "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": {}, - "max_ttl": "768h", - "ttl": "4h" -} -``` -
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/ssh/roles` (LIST) or `/ssh/roles?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```json - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes a named role. -
- -
Method
-
DELETE
- -
URL
-
`/ssh/roles/`
- -
Parameters
-
None
- -
Returns
-
- A `204` response code. -
- -### /ssh/config/zeroaddress - -#### GET - -
-
Description
-
- Returns the list of configured zero-address roles. -
- -
Method
-
GET
- -
URL
-
`/ssh/config/zeroaddress`
- -
Parameters
-
None
- -
Returns
-
- -```json -{ - "lease_id":"", - "renewable":false, - "lease_duration":0, - "data":{ - "roles":[ - "otp_key_role" - ] - }, - "warnings":null, - "auth":null -} -``` - -
- -#### POST - -
-
Description
-
- Configures zero-address roles. -
- -
Method
-
POST
- -
URL
-
`/ssh/config/zeroaddress`
- -
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. -
    • -
-
- -
Returns
-
- A `204` response code. -
- -#### DELETE - -
-
Description
-
- Deletes the zero-address roles configuration. -
- -
Method
-
DELETE
- -
URL
-
`/ssh/config/zeroaddress`
- -
Parameters
-
None
- -
Returns
-
- A `204` response code. -
- - -### /ssh/creds/ -#### POST - -
-
Description
-
- Creates credentials for a specific username and IP with the - parameters defined in the given role. -
- -
Method
-
POST
- -
URL
-
`/ssh/creds/`
- -
Parameters
-
-
    -
  • - username - optional - (String) - Username on the remote host. -
    • -
  • - ip - required - (String) - IP of the remote host. -
    • -
-
- -
Returns
-
For a dynamic key role: - -```json -{ - "lease_id": "", - "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 - }, - "warnings": null, - "auth": null -} -``` - -
- -
For an OTP role: - -```json -{ - "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 -} -``` -
- - -### /ssh/lookup -#### POST - -
-
Description
-
- Lists all of the roles with which the given IP is associated. -
- -
Method
-
POST
- -
URL
-
`/ssh/lookup`
- -
Parameters
-
-
    -
  • - ip - required - (String) - IP of the remote host. -
    • -
-
- -
Returns
-
An array of roles as a secret structure. - -```json -{ - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "roles": ["fe6f61b7-7e4a-46a6-b2c8-0d530b8513df", "6d6411fd-f622-ea0a-7e2c-989a745cbbb2"] - }, - "warnings": null, - "auth": null -} -``` -
- -### /ssh/verify -#### POST - -
-
Description
-
- Verifies if the given OTP is valid. This is an unauthenticated - endpoint. -
- -
Method
-
POST
- -
URL
-
`/ssh/verify`
- -
Parameters
-
-
    -
  • - otp - required - (String) - One-Time-Key that needs to be validated. -
    • -
-
- -
Returns
-
A `200` response code for a valid OTP. - -```json -{ - "lease_id":"", - "renewable":false, - "lease_duration":0, - "data":{ - "ip":"127.0.0.1", - "username":"rajanadar" - }, - "warnings":null, - "auth":null -} -``` - -
- -
A `400` BadRequest response code with 'OTP not found' message, for an invalid OTP.
- -### /ssh/config/ca -#### POST - -
-
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._

-
- -
Method
-
POST
- -
URL
-
`/ssh/config/ca`
- -
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. -
    • -
-
- -
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 - } - ``` -
-
- -#### GET - -
-
Description
-
- Reads the configured/generated public key. -
- -
Method
-
GET
- -
URL
-
`/ssh/config/ca`
- -
Parameters
-
None
- -
Returns
-
- ```json - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "public_key": "ssh-rsa AAAAHHNzaC1y...\n" - }, - "warnings": null - } - ``` -
-
- -### /ssh/sign -#### POST - -
-
Description
-
- Signs an SSH public key based on the supplied parameters, subject to the - restrictions contained in the role named in the endpoint. -
- -
Method
-
POST
- -
URL
-
`/ssh/sign/`
- -
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 -
    • -
-
- -
Returns
-
- - ```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 - } - ``` - -
-
+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. diff --git a/website/source/docs/secrets/transit/index.html.md b/website/source/docs/secrets/transit/index.html.md index ea98384271..422434a595 100644 --- a/website/source/docs/secrets/transit/index.html.md +++ b/website/source/docs/secrets/transit/index.html.md @@ -98,7 +98,7 @@ supports_derivation true supports_encryption true supports_signing false type aes256-gcm96 -```` +``` Now, if we wanted to encrypt a piece of plain text, we use the encrypt endpoint using our named key: @@ -131,925 +131,6 @@ only encrypt or decrypt using the named keys they need access to. ## API -### /transit/keys/ -#### POST - -
-
Description
-
- Creates a new named encryption key of the specified type. The values set - here cannot be changed after key creation. -
- -
Method
-
POST
- -
URL
-
`/transit/keys/`
- -
Parameters
-
-
    -
  • - type - required - The type of key to create. The currently-supported types are: -
      -
    • `aes256-gcm96`: AES-256 wrapped with GCM using a 12-byte nonce size (symmetric)
      • -
    • `ecdsa-p256`: ECDSA using the P-256 elliptic curve (asymmetric)
      • -
    - Defaults to `aes256-gcm96`. -
    • -
  • - derived - optional - Boolean flag indicating if key derivation MUST be used. If enabled, all - encrypt/decrypt requests to this named key must provide a context - which is used for key derivation. Defaults to false. -
    • -
  • - convergent_encryption - optional - If set, the key will support convergent encryption, where the same - plaintext creates the same ciphertext. This requires _derived_ to be - set to `true`. When enabled, each - encryption(/decryption/rewrap/datakey) operation will derive a `nonce` - value rather than randomly generate it. Note that while this is useful - for particular situations, all nonce values used with a given context - value **must be unique** or it will compromise the security of your - key, and the key space for nonces is 96 bit -- not as large as the AES - key itself. Defaults to false. -
    • -
  • - exportable - optional - Boolean flag indicating if the key is exportable. Defaults to false. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Returns information about a named encryption key. The `keys` object shows - the creation time of each key version; the values are not the keys - themselves. Depending on the type of key, different information may be - returned, e.g. an asymmetric key will return its public key in a standard - format for the type. -
- -
Method
-
GET
- -
URL
-
`/transit/keys/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "type": "aes256-gcm96", - "deletion_allowed": false, - "derived": false, - "exportable": false, - "keys": { - "1": 1442851412 - }, - "min_decryption_version": 0, - "name": "foo", - "supports_encryption": true, - "supports_decryption": true, - "supports_derivation": true, - "supports_signing": false - } - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of keys. Only the key names are returned. -
- -
Method
-
LIST/GET
- -
URL
-
`/transit/keys` (LIST) or `/transit/keys?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "keys": ["foo", "bar"] - }, - "lease_duration": 0, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes a named encryption key. - It will no longer be possible to decrypt any data encrypted with the - named key. Because this is a potentially catastrophic operation, the - `deletion_allowed` tunable must be set in the key's `/config` endpoint. -
- -
Method
-
DELETE
- -
URL
-
`/transit/keys/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /transit/keys/config -#### POST - -
-
Description
-
- Allows tuning configuration values for a given key. (These values are - returned during a read operation on the named key.) -
- -
Method
-
POST
- -
URL
-
`/transit/keys//config`
- -
Parameters
-
-
    -
  • - min_decryption_version - optional - The minimum version of ciphertext allowed to be decrypted. Adjusting - this as part of a key rotation policy can prevent old copies of - ciphertext from being decrypted, should they fall into the wrong hands. - For signatures, this value controls the minimum version of signature - that can be verified against. For HMACs, this controls the minimum - version of a key allowed to be used as the key for the HMAC function. - Defaults to 0. -
    • -
  • - deletion_allowed - optional - When set, the key is allowed to be deleted. Defaults to false. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /transit/keys/rotate/ -#### POST - -
-
Description
-
- Rotates the version of the named key. After rotation, new plaintext - requests will be encrypted with the new version of the key. To upgrade - ciphertext to be encrypted with the latest version of the key, use the - `rewrap` endpoint. This is only supported with keys that support encryption - and decryption operations. -
- -
Method
-
POST
- -
URL
-
`/transit/keys//rotate`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /transit/export/encryption-key/\(/\) -### /transit/export/signing-key/\(/\) -### /transit/export/hmac-key/\(/\) -#### GET - -
-
Description
-
- Returns the named key. The `keys` object shows the value of the key for - each version. If `version` is specified, the specific version will be - returned. If `latest` is provided as the version, the current key will be - provided. Depending on the type of key, different information may be - returned. The key must be exportable to support this operation and the - version must still be valid. -
- -
Method
-
GET
- -
URL
-
`/transit/export///`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "name": "foo", - "keys": { - "1": "eyXYGHbTmugUJn6EtYD/yVEoF6pCxm4R/cMEutUm3MY=", - "2": "Euzymqx6iXjS3/NuGKDCiM2Ev6wdhnU+rBiKnJ7YpHE=" - } - } - } - ``` - -
-
- -### /transit/encrypt/ -#### POST - -
-
Description
-
- Encrypts the provided plaintext using the named key. Currently, this only - supports symmetric keys. This path supports the `create` and `update` - policy capabilities as follows: if the user has the `create` capability for - this endpoint in their policies, and the key does not exist, it will be - upserted with default values (whether the key requires derivation depends - on whether the context parameter is empty or not). If the user only has - `update` capability and the key does not exist, an error will be returned. -
- -
Method
-
POST
- -
URL
-
`/transit/encrypt/`
- -
Parameters
-
-
    -
  • - plaintext - required - Base64 encoded plaintext value to be encrypted. -
    • -
-
    -
  • - context - optional - Base64 encoded context for key derivation. Required if key derivation - is enabled. -
    • -
-
    -
  • - nonce - optional - Base64 encoded nonce value. Must be provided if convergent encryption is - enabled for this key and the key was generated with Vault 0.6.1. Not required - for keys created in 0.6.2+. The value must be exactly 96 bits (12 bytes) long - and the user must ensure that for any given context (and thus, any given - encryption key) this nonce value is **never reused**. -
    • -
-
    -
  • - batch_input - optional - List of items to be encrypted in a single batch. When - this parameter is set, if the parameters 'plaintext', 'context' and - 'nonce' are also set, they will be ignored. Format for the input - goes like this: - -```javascript -[ - { - "context": "c2FtcGxlY29udGV4dA==", - "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA==" - }, - { - "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", - "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA==" - }, - ... -] -``` - -
    • -
-
    -
  • - type - optional - This parameter is required when encryption key is expected to be created. - When performing an upsert operation, the type of key to create. Currently, - "aes256-gcm96" (symmetric) is the only type supported. Defaults to - "aes256-gcm96". -
    • -
-
    -
  • - convergent_encryption - optional - This parameter will only be used when a key is expected to be created. Whether - to support convergent encryption. This is only supported when using a key with - key derivation enabled and will require all requests to carry both a context - and 96-bit (12-byte) nonce. The given nonce will be used in place of a randomly - generated nonce. As a result, when the same context and nonce are supplied, the - same ciphertext is generated. It is *very important* when using this mode that - you ensure that all nonces are unique for a given context. Failing to do so - will severely impact the ciphertext's security. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "ciphertext": "vault:v1:abcdefgh" - } - } - ``` - -
-
- -### /transit/decrypt/ -#### POST - -
-
Description
-
- Decrypts the provided ciphertext using the named key. Currently, this only - supports symmetric keys. -
- -
Method
-
POST
- -
URL
-
`/transit/decrypt/`
- -
Parameters
-
-
    -
  • - ciphertext - required - The ciphertext to decrypt, provided as returned by encrypt. -
    • -
  • - context - optional - Base64 encoded context for key derivation. Required if key derivation is - enabled. -
    • -
  • - nonce - optional - Base64 encoded nonce value used during encryption. Must be provided if - convergent encryption is enabled for this key and the key was generated with - Vault 0.6.1. Not required for keys created in 0.6.2+. -
    • -
-
    -
  • - batch_input - optional - List of items to be decrypted in a single batch. When this parameter is - set, if the parameters 'ciphertext', 'context' and 'nonce' are also - set, they will be ignored. Format for the input goes like this: - -```javascript -[ - { - "context": "c2FtcGxlY29udGV4dA==", - "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI=" - }, - { - "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", - "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" - }, - ... -] -``` - -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=" - } - } - ``` - -
-
- -### /transit/rewrap/ -#### POST - -
-
Description
-
- Rewrap the provided ciphertext using the latest version of the named key. - Because this never returns plaintext, it is possible to delegate this - functionality to untrusted users or scripts. -
- -
Method
-
POST
- -
URL
-
`/transit/rewrap/`
- -
Parameters
-
-
    -
  • - ciphertext - required - The ciphertext to decrypt, provided as returned by encrypt. -
    • -
  • - context - optional - Base64 encoded context for key derivation. Required for derived keys. -
    • -
  • - nonce - optional - The nonce value used during encryption, provided as base64 encoded. - Must be provided if convergent encryption is enabled for this key and - the key was created with Vault 0.6.1. Not required for keys created in - 0.6.2+. -
    • -
  • - batch_input - optional - List of items to be rewrapped in a single batch. When this parameter is - set, if the parameters 'ciphertext', 'context' and 'nonce' are also - set, they will be ignored. Format for the input goes like this: - -```javascript -[ - { - "context": "c2FtcGxlY29udGV4dA==", - "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI=" - }, - { - "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", - "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" - }, - ... -] -``` - -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "ciphertext": "vault:v2:abcdefgh" - } - } - ``` - -
-
- -### /transit/datakey/ -#### POST - -
-
Description
-
- Generate a new high-entropy key and the value encrypted with the named - key. Optionally return the plaintext of the key as well. Whether plaintext - is returned depends on the path; as a result, you can use Vault ACL - policies to control whether a user is allowed to retrieve the plaintext - value of a key. This is useful if you want an untrusted user or operation - to generate keys that are then made available to trusted users. -
- -
Method
-
POST
- -
URL
-
`/transit/datakey//`
- -
Parameters
-
-
    -
  • - plaintext|wrapped (path parameter) - required - If `plaintext`, the plaintext key will be returned along with the - ciphertext. If `wrapped`, only the ciphertext value will be returned. -
    • -
  • - context - optional - The key derivation context, provided as a base64-encoded string. - Must be provided if derivation is enabled. -
    • -
  • - nonce - optional - The nonce value, provided as base64 encoded. Must be provided if - convergent encryption is enabled for this key and the key was generated - with Vault 0.6.1. Not required for keys created in 0.6.2+. The value - must be exactly 96 bits (12 bytes) long and the user must ensure that - for any given context (and thus, any given encryption key) this nonce - value is **never reused**. -
    • -
  • - bits - optional - The number of bits in the desired key. Can be 128, 256, or 512; if not - given, defaults to 256. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=", - "ciphertext": "vault:v1:abcdefgh" - } - } - ``` - -
-
- -### /transit/random -#### POST - -
-
Description
-
- Return high-quality random bytes of the specified length. -
- -
Method
-
POST
- -
URL
-
`/transit/random(/)`
- -
Parameters
-
-
    -
  • - bytes - optional - The number of bytes to return. Defaults to 32 (256 bits). This value - can be specified either in the request body, or as a part of the URL - with a format like `/transit/random/48`. -
    • -
  • - format - optional - The output encoding; can be either `hex` or `base64`. Defaults to - `base64`. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "random_bytes": "dGhlIHF1aWNrIGJyb3duIGZveAo=" - } - } - ``` - -
-
- -### /transit/hash -#### POST - -
-
Description
-
- Returns the hash of given data using the specified algorithm. The algorithm - can be specified as part of the URL or given via a parameter; the URL value - takes precedence if both are set. -
- -
Method
-
POST
- -
URL
-
`/transit/hash(/)`
- -
Parameters
-
-
    -
  • - input - required - The base64-encoded input data. -
    • -
  • - algorithm - optional - The hash algorithm to use. This can also be specified in the URL. - Currently-supported algorithms are: -
      -
    • `sha2-224`
      • -
    • `sha2-256`
      • -
    • `sha2-384`
      • -
    • `sha2-512`
      • -
    - Defaults to `sha2-256`. -
    • -
  • - format - optional - The output encoding; can be either `hex` or `base64`. Defaults to - `hex`. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "sum": "dGhlIHF1aWNrIGJyb3duIGZveAo=" - } - } - ``` - -
-
- -### /transit/hmac/ -#### POST - -
-
Description
-
- Returns the digest of given data using the specified hash algorithm and the - named key. The key can be of any type supported by `transit`; the raw key - will be marshalled into bytes to be used for the HMAC function. If the key - is of a type that supports rotation, the latest (current) version will be - used. -
- -
Method
-
POST
- -
URL
-
`/transit/hmac/(/)`
- -
Parameters
-
-
    -
  • - input - required - The base64-encoded input data. -
    • -
  • - algorithm - optional - The hash algorithm to use. This can also be specified in the URL. - Currently-supported algorithms are: -
      -
    • `sha2-224`
      • -
    • `sha2-256`
      • -
    • `sha2-384`
      • -
    • `sha2-512`
      • -
    - Defaults to `sha2-256`. -
    • -
  • - format - optional - The output encoding; can be either `hex` or `base64`. Defaults to - `hex`. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "hmac": "dGhlIHF1aWNrIGJyb3duIGZveAo=" - } - } - ``` - -
-
- -### /transit/sign/ -#### POST - -
-
Description
-
- Returns the cryptographic signature of the given data using the named key - and the specified hash algorithm. The key must be of a type that supports - signing. -
- -
Method
-
POST
- -
URL
-
`/transit/sign/(/)`
- -
Parameters
-
-
    -
  • - input - required - The base64-encoded input data. -
    • -
  • - algorithm - optional - The hash algorithm to use. This can also be specified in the URL. - Currently-supported algorithms are: -
      -
    • `sha2-224`
      • -
    • `sha2-256`
      • -
    • `sha2-384`
      • -
    • `sha2-512`
      • -
    - Defaults to `sha2-256`. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "signature": "vault:v1:MEUCIQCyb869d7KWuA0hBM9b5NJrmWzMW3/pT+0XYCM9VmGR+QIgWWF6ufi4OS2xo1eS2V5IeJQfsi59qeMWtgX0LipxEHI=" - } - } - ``` - -
-
- -### /transit/verify/ -#### POST - -
-
Description
-
- Returns whether the provided signature is valid for the given data. -
- -
Method
-
POST
- -
URL
-
`/transit/verify/(/)`
- -
Parameters
-
-
    -
  • - input - required - The base64-encoded input data. -
    • -
  • - signature - required - The signature output from the `/transit/sign` function. Either this must be supplied or `hmac` must be supplied. -
    • -
  • - hmac - required - The signature output from the `/transit/hmac` function. Either this must be supplied or `signature` must be supplied. -
    • -
  • - algorithm - optional - The hash algorithm to use. This can also be specified in the URL. - Currently-supported algorithms are: -
      -
    • `sha2-224`
      • -
    • `sha2-256`
      • -
    • `sha2-384`
      • -
    • `sha2-512`
      • -
    - Defaults to `sha2-256`. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "valid": true - } - } - ``` - -
-
+The Transit secret backend has a full HTTP API. Please see the +[Transit secret backend API](/docs/http/secret/transit/index.html) for more +details. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 39e43e7602..053db3a7c1 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -154,10 +154,6 @@ - > - API & Libraries - -
> @@ -289,6 +285,10 @@
+ > + API & Libraries + + > Guides