diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki.mdx index ebae68343..e350b96a1 100644 --- a/website/content/api-docs/secret/pki.mdx +++ b/website/content/api-docs/secret/pki.mdx @@ -38,6 +38,7 @@ update your API calls accordingly. - [Managing Keys and Issuers](#managing-keys-and-issuers) - [List Issuers](#list-issuers) - [List Keys](#list-keys) + - [Generate Key](#generate-key) - [Generate Root](#generate-root) - [Generate Intermediate CSR](#generate-intermediate-csr) - [Import CA Certificates and Keys](#import-ca-certificates-and-keys) @@ -1172,6 +1173,91 @@ $ curl \ } ``` +### Generate Key + +This endpoint generates a new private key for use in the PKI mount. This key +can be used with either the [root](#generate-root) or [intermediate](#generate-intermediate-csr) +endpoints, using the `type=existing` variant. + +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_; if it is `kms`, a [managed keys](#managed-keys) will be +used. + +| Method | Path | +| :----- | :--------------------------------- | +| `POST` | `/pki/keys/generate/:type` | + +#### Parameters + +- `type` `(string: )` - Specifies the type of the root to + create. If `exported`, the private key will be returned in the response; if + `internal` the private key will not be returned and _cannot be retrieved + later_; `kms` is also supported: [see below for more details about managed + keys](#managed-keys). This parameter is part of the request URL. + +- `key_name` `(string: "")` - When a new key is created with this request, + optionally specifies the name for this. The global ref `default` may not + be used as a name. + +- `key_type` `(string: "rsa")` - Specifies the desired key type; must be `rsa`, `ed25519` + or `ec`. + +~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified + and thus should not be used: `ed25519`. + +- `key_bits` `(int: 0)` - Specifies the number of bits to use for the + generated keys. Allowed values are 0 (universal default); with + `key_type=rsa`, allowed values are: 2048 (default), 3072, or + 4096; with `key_type=ec`, allowed values are: 224, 256 (default), + 384, or 521; ignored with `key_type=ed25519`. + +#### Managed Keys Parameters + +See [Managed Keys](#managed-keys) for additional details on this feature, if +`type` was set to `kms`. One of the following parameters must be set + +- `managed_key_name` `(string: "")` - The managed key's configured name. + +- `managed_key_id` `(string: "")` - The managed key's UUID. + +#### Sample Payload + +```json +{ + "key_type": "ec", + "key_bits": "256", + "key_name": "root-key-2022" +} +``` + +#### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/keys/generate/internal +``` + +#### Sample Response + +```json +{ + "request_id": "8ad22b2f-7d14-f2cd-a10a-d1abc33676ab", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "key_id": "adda2443-a8aa-d181-9d07-07c7be6a76ab", + "key_name": "root-key-2022", + "key_type": "ec" + }, + "warnings": null +} +``` + ### Generate Root This endpoint generates a new self-signed CA certificate and private key. If @@ -1214,6 +1300,10 @@ use the values set via `config/urls`. optionally specifies the name for this. The global ref `default` may not be used as a name. +- `key_ref` `(string: "default")` - Specifies the key (either `default`, by + name, or by identifier) to use for generating this request. Only suitable + for `type=existing` requests. + - `common_name` `(string: )` - Specifies the requested CN for the certificate. If more than one `common_name` is desired, specify the alternative names in the `alt_names` list. diff --git a/website/content/docs/secrets/pki/considerations.mdx b/website/content/docs/secrets/pki/considerations.mdx index 78dcae78e..3784043f7 100644 --- a/website/content/docs/secrets/pki/considerations.mdx +++ b/website/content/docs/secrets/pki/considerations.mdx @@ -444,6 +444,10 @@ For these personas, we suggest the following ACLs, in condensed, tabular form: | `/root/rotate/+` | Write | Yes | | | | | | `/root/replace` | Write | Yes | | | | | +~> Note: With managed keys, operators might need access to [read the mount + point's tunable data](/api-docs/system/mounts) (Read on `/sys/mounts`) and + may need access [to use or manage managed keys](/api-docs/system/managed-keys). + ## Replicated DataSets When operating with [Performance Secondary](/docs/enterprise/replication#architecture)