From 262b0434dff133cde5ba4e7d1a95535052ba76c0 Mon Sep 17 00:00:00 2001
From: Kit Haines <khaines@mit.edu>
Date: Thu, 30 Mar 2023 07:31:48 -0400
Subject: [PATCH] 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>
---
 website/content/docs/commands/pki/index.mdx   | 64 ++++++++++++-
 website/content/docs/commands/pki/issue.mdx   | 72 +++++++++++++++
 .../docs/commands/pki/list-intermediates.mdx  | 89 +++++++++++++++++++
 website/content/docs/commands/pki/reissue.mdx | 88 ++++++++++++++++++
 .../content/docs/commands/pki/verify-sign.mdx | 56 ++++++++++++
 website/data/docs-nav-data.json               | 18 +++-
 6 files changed, 385 insertions(+), 2 deletions(-)
 create mode 100644 website/content/docs/commands/pki/issue.mdx
 create mode 100644 website/content/docs/commands/pki/list-intermediates.mdx
 create mode 100644 website/content/docs/commands/pki/reissue.mdx
 create mode 100644 website/content/docs/commands/pki/verify-sign.mdx

diff --git a/website/content/docs/commands/pki/index.mdx b/website/content/docs/commands/pki/index.mdx
index b6c054ca5e8b..8a6ec3379407 100644
--- a/website/content/docs/commands/pki/index.mdx
+++ b/website/content/docs/commands/pki/index.mdx
@@ -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```
diff --git a/website/content/docs/commands/pki/issue.mdx b/website/content/docs/commands/pki/issue.mdx
new file mode 100644
index 000000000000..674f1fa4f87b
--- /dev/null
+++ b/website/content/docs/commands/pki/issue.mdx
@@ -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...
+```
diff --git a/website/content/docs/commands/pki/list-intermediates.mdx b/website/content/docs/commands/pki/list-intermediates.mdx
new file mode 100644
index 000000000000..aa0606c3e4c4
--- /dev/null
+++ b/website/content/docs/commands/pki/list-intermediates.mdx
@@ -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
+```
diff --git a/website/content/docs/commands/pki/reissue.mdx b/website/content/docs/commands/pki/reissue.mdx
new file mode 100644
index 000000000000..cb11d5a6c9ac
--- /dev/null
+++ b/website/content/docs/commands/pki/reissue.mdx
@@ -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```
diff --git a/website/content/docs/commands/pki/verify-sign.mdx b/website/content/docs/commands/pki/verify-sign.mdx
new file mode 100644
index 000000000000..ec4c68a7f2cb
--- /dev/null
+++ b/website/content/docs/commands/pki/verify-sign.mdx
@@ -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
+```
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index 4260aef91243..ce14ec871ce0 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -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"
+	  }
         ]
       },
       {