More PKI docs updates (#15757)
* Add missing key_ref parameter to gen root docs Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Add API docs section on key generation Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Add note about managed key access Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>
This commit is contained in:
Alexander Scheel
GitHub
parent
ad1796680e
commit
ab10435ab7
|
|
@ -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: <required>)` - 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: <required>)` - Specifies the requested CN for the
|
||||
certificate. If more than one `common_name` is desired, specify the
|
||||
alternative names in the `alt_names` list.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue