mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-10-29 17:52:32 +00:00
Add PKI-CLI to docs (#19669)
* Add pki-cli docs. * Tiny updates. * Whitespace fix, include description * Closing-tags. * Update website/content/docs/commands/pki/verify-sign.mdx Title Code as Shell Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com> * Update website/content/docs/commands/pki/reissue.mdx Title More Code as Shell Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com> * Update website/content/docs/commands/pki/list-intermediates.mdx Title code block as shell Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com> * Update website/content/docs/commands/pki/issue.mdx Title code-block as shell Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com> * Apply suggestions from code review Label Code-Blocks as Shell-Session Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com> * Apply suggestions from code review Comma and Period Changes. Co-authored-by: Alexander Scheel <alex.scheel@hashicorp.com> * Apply suggestions from code review ascheels highlighting-1 Co-authored-by: Alexander Scheel <alex.scheel@hashicorp.com> * Fix highlighting throughout. * Update website/content/docs/commands/pki/list-intermediates.mdx Co-authored-by: Alexander Scheel <alex.scheel@hashicorp.com> * Update website/content/docs/commands/pki/reissue.mdx Clarifying note on why unknown fields might be there. Co-authored-by: Alexander Scheel <alex.scheel@hashicorp.com> * Update website/content/docs/commands/pki/reissue.mdx cipherboy request Co-authored-by: Alexander Scheel <alex.scheel@hashicorp.com> * Add Key-ID RFC link. * k=v add link * correct link --------- Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com> Co-authored-by: Alexander Scheel <alex.scheel@hashicorp.com>
This commit is contained in:
Kit Haines
@@ -15,7 +15,7 @@ The `pki` command groups subcommands for interacting with Vault's
|
||||
|
||||
Option flags for a given subcommand are provided after the subcommand, but before the arguments.
|
||||
|
||||
## Examples
|
||||
## Example Health Check
|
||||
|
||||
To [health check](/vault/docs/commands/pki/health-check) a mount, use the
|
||||
`vault pki health-check <mount>` command:
|
||||
@@ -30,3 +30,65 @@ ok /pki/issuer/da41ffb1-cc6d-5a5c-f147-e4d7beeb1b73 Issuer's validity
|
||||
|
||||
... more output elided ...
|
||||
```
|
||||
|
||||
## Example Verify Sign
|
||||
|
||||
To [verify](/vault/docs/commands/pki/verify-sign) the signature between two
|
||||
issuer certificates, use the `vault pki verify-sign <parent> <child>` command:
|
||||
|
||||
```shell-session
|
||||
$ vault pki verify-sign pki_root/issuer/root pki_int/issuer/FirstDepartment
|
||||
issuer:pki_root/issuer/root
|
||||
issued:pki_int/issuer/FirstDepartment
|
||||
|
||||
field value
|
||||
----- -----
|
||||
subject_match true
|
||||
path_match true
|
||||
trust_match true
|
||||
key_id_match true
|
||||
signature_match true
|
||||
```
|
||||
|
||||
## Example List Child Issuers
|
||||
|
||||
To [list intermediate](/vault/docs/commands/pki/list-intermediates) certificates
|
||||
potentially issued by a certificate inside vault, use the
|
||||
`vault pki list-intermediates <parent>` command:
|
||||
|
||||
```shell-session
|
||||
$ vault pki list-intermediates /pki_root/issuer/default
|
||||
intermediate match?
|
||||
------------ ------
|
||||
pki_int_2/issuer/d4404ccc-3ad4-83a9-f5df-398637654b3b true
|
||||
pki_int_2/issuer/db0b0a6c-6641-ac15-363a-4e5261315581 true
|
||||
pki_root/issuer/9464c4fe-e8a6-d96a-0566-021575e7382c true
|
||||
pki_int/issuer/2f958ec5-1838-336e-331b-07032379b958 true
|
||||
pki_int/issuer/b8cc0b41-e0e9-1a92-12c4-6849c9d6f837 true
|
||||
```
|
||||
|
||||
## Example Issue
|
||||
|
||||
To [issue](/vault/docs/commands/pki/issue) a new issuer certificate, use the
|
||||
`vault pki issue <parent-certificate-path> <mount>` command:
|
||||
|
||||
```shell-session
|
||||
$ vault pki issue -issuer_name="FirstDepartment" /pki_root/issuer/default /pki_int/ common_name="first-department.example.com"
|
||||
Key Value
|
||||
--- -----
|
||||
ca_chain [-----BEGIN CERTIFICATE-----
|
||||
MIIDsDCCApigAwIBAgIULEPuHTW7UDtAQg+qcc18osNWgZIwDQYJKoZIhvcNAQEL...
|
||||
```
|
||||
|
||||
## Example Reissue
|
||||
|
||||
To [reissue](/vault/docs/commands/pki/reissue) an issuer certificate, using the
|
||||
same fields as an existing issuer template, use the
|
||||
`vault pki reissue <parent-certificate-path> <template> <mount>` command:
|
||||
|
||||
```shell-session
|
||||
$ vault pki reissue -issuer_name="SecondDepartment" /pki_root/issuer/default /pki_int/issuer/FirstDepartment /pki_int_2/ common_name="second-department.example.com"
|
||||
Key Value
|
||||
--- -----
|
||||
ca_chain [-----BEGIN CERTIFICATE-----
|
||||
MIID0DCCArigAwIBAgIUdfRe05B5eRXsg3pvsJ/g94eYuWkwDQYJKoZIhvcNAQEL```
|
||||
|
||||
72
website/content/docs/commands/pki/issue.mdx
Normal file
72
website/content/docs/commands/pki/issue.mdx
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: pki issue - Command
|
||||
description: |-
|
||||
The "pki issue" command issues a new intermediate ("issuer") certificate,
|
||||
using a parent certificate in vault.
|
||||
---
|
||||
|
||||
# pki issue
|
||||
|
||||
This command creates a intermediate certificate authority certificate signed by
|
||||
the `<parent>` in the `<child_mount>`, using the options to determine the fields
|
||||
on that certificate.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `vault pki issue [flags] <parent> <child_mount> [options]`
|
||||
|
||||
- `[flags]` are optional arguments described below
|
||||
|
||||
- `<parent>` is the fully qualified path of the Certificate Authority in vault
|
||||
which will issue the new intermediate certificate.
|
||||
|
||||
- `<child_mount>` is the path of the mount in vault where the new issuer is saved.
|
||||
|
||||
- `[options]` are the superset of the k=v options passed to generate-intermediate-csr
|
||||
and sign-intermediate commands. At least one option must be set.
|
||||
See [below](/vault/docs/commands/pki/issue#options).
|
||||
|
||||
### Flags
|
||||
|
||||
- `-type` `(string: "internal")` - This determines the type of key use for the
|
||||
newly created certificate. Valid types are `"existing"` - where we link to
|
||||
a key already present in the vault-backend to be used (and expect option
|
||||
arguments `"key_ref"`) - `"internal"` - to generate a new key for this
|
||||
certificate - or `"kms"` - to link to an external key. Exported keys are not
|
||||
available through this API.
|
||||
|
||||
- `-issuer_name` `(string: "")` - If present, the newly created issuer will be
|
||||
given this name.
|
||||
|
||||
### Options
|
||||
|
||||
Other than `type` (which is passed as a flag, see above), this command accepts
|
||||
all options provided to the
|
||||
[Generate CSR](/vault/api-docs/secret/pki#generate-intermediate-csr) and
|
||||
[Sign Intermediate](/vault/api-docs/secret/pki#sign-intermediate) endpoints.
|
||||
|
||||
### Accessed APIs
|
||||
|
||||
Note that the vault user running this command will need to have access to the
|
||||
following API endpoints, each representing a step in the process:
|
||||
|
||||
- `READ /:parent` - used to check validity
|
||||
- `WRITE /:child_mount/intermediate/generate/:type` - used to generate the csr
|
||||
- `WRITE /:parent/sign-intermediate` - used to sign the csr
|
||||
- `WRITE /:child_mount/issuers/import/cert` - used to import the new issuer,
|
||||
and the issuer chain
|
||||
- `UPDATE /:child_mount/issuer/:issuer_refs` - used to both name the new
|
||||
issuer, and also set the name of the parent in the issuer chain
|
||||
- `READ /:child_mount/issuer/:new_issuer_ref` - used to verify completion,
|
||||
generate the output
|
||||
|
||||
## Examples
|
||||
|
||||
```shell-session
|
||||
$ vault pki issue -issuer_name="FirstDepartment" /pki_root/issuer/default /pki_int/ common_name="first-department.example.com"
|
||||
Key Value
|
||||
--- -----
|
||||
ca_chain [-----BEGIN CERTIFICATE-----
|
||||
MIIDsDCCApigAwIBAgIULEPuHTW7UDtAQg+qcc18osNWgZIwDQYJKoZIhvcNAQEL...
|
||||
```
|
||||
89
website/content/docs/commands/pki/list-intermediates.mdx
Normal file
89
website/content/docs/commands/pki/list-intermediates.mdx
Normal file
@@ -0,0 +1,89 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: pki list-intermediates - Command
|
||||
description: |-
|
||||
The "pki list-intermediates" command searches a mount, or set of mounts for
|
||||
child certificates.
|
||||
---
|
||||
|
||||
# pki list-intermediates
|
||||
|
||||
This command determines which of a list of certificates were issued by a given
|
||||
parent certificate.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `vault pki list-intermediates [flags] <parent> [child] [child] [child...`
|
||||
|
||||
Lists the set of intermediate CAs issued by this parent issuer.
|
||||
|
||||
- `[flags]` listed below determine the type of match required between the `<parent>`
|
||||
and each potential child, and the type of output
|
||||
|
||||
- `<parent>` is the certificate that might be the issuer which everything is
|
||||
verified against.
|
||||
|
||||
- `[child]` is an optional path to a certificate to be compared to the `<parent>`,
|
||||
or pki mounts to look for certificates on. If `[child]` is omitted entirely, the
|
||||
list will be constructed from all accessible pki mounts.
|
||||
|
||||
This returns a list of issuing certificates and whether they are a match.
|
||||
By default, the type of match required is whether the `<parent>` has the
|
||||
expected subject, [authority/subject key id match](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.1), and could have (directly) signed this issuer.
|
||||
The match criteria can be updated by changed the corresponding flag.
|
||||
|
||||
### Flags
|
||||
|
||||
- `-use_names` `(bool: "false")` - this determines how issuers are referred to
|
||||
in the output, whether by issuer_id (the default), or by their name, or status
|
||||
as default issuer (when use_names is true)
|
||||
|
||||
The following flags determine what sorts of relationship between the parent and
|
||||
potential child issuers are considered a match.
|
||||
|
||||
- `-subject_match` `(bool: "true")` - determines whether the subject of the
|
||||
parent-issuer must match the issuer of the potential child for this to be
|
||||
considered a match
|
||||
|
||||
- `-key_id_match` `(bool: "true")` - determines whether the identifier of the
|
||||
parent-issuer must match the IUI of the potential child for this to be
|
||||
considered a match
|
||||
|
||||
- `-direct_verify` `(bool: "true")` - determines whether it is required for this
|
||||
to be a match that someone trusting the parent certificate would trust the
|
||||
potential-child certificate (without any more information)
|
||||
|
||||
- `-indirect-sign` `(bool: "true")` - determines whether it is required for this
|
||||
to be a match that if someone trusted the first certificate, they would trust
|
||||
the potential-child certificate (using the certificate chains available)
|
||||
|
||||
- `-path_contains` `(bool: "false")` - determines whether it is required for
|
||||
this to be a match for the ca_chain of the potential child certificate to
|
||||
contain the parent certificate
|
||||
|
||||
### Accessed APIs
|
||||
|
||||
Note that the vault user running this command will need to have access to the
|
||||
following API endpoints, each representing a step in the process:
|
||||
|
||||
- `READ /:parent`
|
||||
- `LIST /sys/mounts` - when no `[child]` argument is provided, this is used to
|
||||
find a list of pki mounts
|
||||
- `LIST /:child_mount/issuers/` - when no `[child]` argument is provided, or the
|
||||
`[child]` argument is a mount rather than an issuer, this is used to find a list
|
||||
of pki issuers on the mount
|
||||
- `READ /:child` - each potential child issuer is read for comparison against
|
||||
the parent
|
||||
|
||||
## Examples
|
||||
|
||||
```shell-session
|
||||
$ vault pki list-intermediates /pki_root/issuer/default
|
||||
intermediate match?
|
||||
------------ ------
|
||||
pki_int_2/issuer/d4404ccc-3ad4-83a9-f5df-398637654b3b true
|
||||
pki_int_2/issuer/db0b0a6c-6641-ac15-363a-4e5261315581 true
|
||||
pki_root/issuer/9464c4fe-e8a6-d96a-0566-021575e7382c true
|
||||
pki_int/issuer/2f958ec5-1838-336e-331b-07032379b958 true
|
||||
pki_int/issuer/b8cc0b41-e0e9-1a92-12c4-6849c9d6f837 true
|
||||
```
|
||||
88
website/content/docs/commands/pki/reissue.mdx
Normal file
88
website/content/docs/commands/pki/reissue.mdx
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: pki reissue - Command
|
||||
description: |-
|
||||
The "pki reissue" command issues a new intermediate ("issuer") certificate,
|
||||
using an existing certificate in vault as a template, and using a parent
|
||||
certificate in vault to issue the new certificate.
|
||||
---
|
||||
|
||||
# pki reissue
|
||||
|
||||
Frequently, a reissued CA certificate is to be very similar to another.
|
||||
This command enables reissuing a CA, using an existing issuer within
|
||||
Vault as a template, but allowing modifications to the desired attributes.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `vault pki reissue [flags] <parent> <template> <child_mount> [options]`
|
||||
|
||||
- `[flags]` are optional arguments described below.
|
||||
|
||||
- `<parent>` is the fully qualified path of the Certificate Authority in vault
|
||||
which will issue the new intermediate certificate.
|
||||
|
||||
- `<template>` is the fully qualified path of an intermediate certificate in vault
|
||||
which will be used to populate certificate fields not overridden by `[options]`.
|
||||
|
||||
~> **Note**: not all possible certificate fields are supported by Vault, and
|
||||
this template reader covers only those vault generates as a best effort. If
|
||||
unknown fields are set, such as when an external CA was imported into Vault,
|
||||
there may not be a warning that those are missing from the new issuer.
|
||||
|
||||
- `<child_mount>` is the path of the mount in vault where the new issuer is saved.
|
||||
|
||||
- `[options]` are the superset of the k=v options passed to generate/intermediate
|
||||
and sign-intermediate commands. See [below](/vault/docs/commands/pki/reissue#options).
|
||||
|
||||
The output of this command when it is successful is to read the resulting new
|
||||
issuer entry.
|
||||
|
||||
### Flags
|
||||
|
||||
- `-type` `(string: "internal")` - This determines the type of key use for the
|
||||
newly created certificate. Valid types are `"existing"` - where we link to
|
||||
a key already present in the vault-backend to be used - `"internal"` - to
|
||||
generate a new key for this certificate - or `"kms"` - to link to an external
|
||||
key. Exported keys are not available through this API.
|
||||
|
||||
~> **Note**: It is only possible to generate a new certificate with an existing
|
||||
key that exists in the same mount where that key-material exists. This
|
||||
command is expected to fail should the template exist on a different mount,
|
||||
`existing` is the selected type, and no `key_ref` for a key in the new issuer
|
||||
mount is provided.
|
||||
|
||||
- `-issuer_name` `(string: "")` - If present, the newly created issuer will be
|
||||
given this name.
|
||||
|
||||
### Options
|
||||
|
||||
Other than `type` (which is passed as a flag, see above), this command accepts
|
||||
all options provided to the
|
||||
[Generate CSR](/vault/api-docs/secret/pki#generate-intermediate-csr) and
|
||||
[Sign Intermediate](/vault/api-docs/secret/pki#sign-intermediate) endpoints.
|
||||
|
||||
### Accessed APIs
|
||||
|
||||
Note that the vault user running this command will need to have access to the
|
||||
following API endpoints, each representing a step in the process:
|
||||
|
||||
- `READ /:parent` - used to check validity
|
||||
- `READ /:template` - used to generate the options for the new certificate
|
||||
- `WRITE /:child_mount/intermediate/generate/:type` - used to generate the csr
|
||||
- `WRITE /:parent/sign-intermediate` - used to sign the csr
|
||||
- `WRITE /:child_mount/issuers/import/cert` - used to import the new issuer,
|
||||
and the issuer chain
|
||||
- `UPDATE /:child_mount/issuer/:issuer_refs` - used to both name the new
|
||||
issuer, and also set the name of the parent in the issuer chain
|
||||
- `READ /:child_mount/issuer/:new_issuer_ref` - used to verify completion,
|
||||
generate the output
|
||||
|
||||
## Examples
|
||||
|
||||
```shell-session
|
||||
$ vault pki reissue -issuer_name="SecondDepartment" /pki_root/issuer/default /pki_int/issuer/FirstDepartment /pki_int_2/ common_name="second-department.example.com"
|
||||
Key Value
|
||||
--- -----
|
||||
ca_chain [-----BEGIN CERTIFICATE-----
|
||||
MIID0DCCArigAwIBAgIUdfRe05B5eRXsg3pvsJ/g94eYuWkwDQYJKoZIhvcNAQEL```
|
||||
56
website/content/docs/commands/pki/verify-sign.mdx
Normal file
56
website/content/docs/commands/pki/verify-sign.mdx
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: pki verify-sign - Command
|
||||
description: |-
|
||||
The "pki verify-sign" command verifies the relationship between two issuer
|
||||
certificates in vault
|
||||
---
|
||||
|
||||
# pki verify-sign
|
||||
|
||||
This command verifies whether the listed issuer has signed the listed issued
|
||||
certificate.
|
||||
|
||||
This command returns five fields of information:
|
||||
|
||||
- `signature_match`: was the key of the issuer used to sign the issued.
|
||||
|
||||
- `path_match`: the possible issuer appears in the valid certificate chain
|
||||
of the issued.
|
||||
|
||||
- `key_id_match`: does the [key id](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.1)
|
||||
of the issuer match the key_id of the subject.
|
||||
|
||||
- `subject_match`: does the subject name of the issuer match the issuer
|
||||
subject of the issued.
|
||||
|
||||
- `trust_match`: if someone trusted the parent issuer, is the chain
|
||||
provided sufficient to trust the child issued.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `vault pki verify-sign <parent> <child>`
|
||||
|
||||
- `<parent>` is the fully name-spaced path to the issuer certificate which will be
|
||||
used to verify the `<child>` certificate
|
||||
|
||||
- `<child>` is the fully name-spaced path to the potential child-certificate to be
|
||||
verified
|
||||
|
||||
A fully namespaced path looks like, for instance, 'ns1/mount1/issuer/issuerName/json'.
|
||||
|
||||
## Example
|
||||
|
||||
```shell-session
|
||||
$ vault pki verify-sign pki_root/issuer/root pki_int/issuer/FirstDepartment
|
||||
issuer:pki_root/issuer/root
|
||||
issued:pki_int/issuer/FirstDepartment
|
||||
|
||||
field value
|
||||
----- -----
|
||||
subject_match true
|
||||
path_match true
|
||||
trust_match true
|
||||
key_id_match true
|
||||
signature_match true
|
||||
```
|
||||
@@ -570,7 +570,23 @@
|
||||
{
|
||||
"title": "<code>health-check</code>",
|
||||
"path": "commands/pki/health-check"
|
||||
}
|
||||
},
|
||||
{
|
||||
"title": "<code>verify-sign</code>",
|
||||
"path": "commands/pki/verify-sign"
|
||||
},
|
||||
{
|
||||
"title": "<code>list-intermeidates</code>",
|
||||
"path": "commands/pki/list-intermediates"
|
||||
},
|
||||
{
|
||||
"title": "<code>issue</code>",
|
||||
"path": "commands/pki/issue"
|
||||
},
|
||||
{
|
||||
"title": "<code>reissue</code>",
|
||||
"path": "commands/pki/reissue"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user