Update more PKI documentation (#14490)

* Update description of certificate fetch API

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Clarify /config/crl and /config/url PKI are empty

GET-ing these URLs will return 404 until such time as a config is posted
to them, even though (in the case of CRL), default values will be used.

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Clarify usage of /pki/crl/rotate

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Update documentation around PKI key_bits

This unifies the description of key_bits to match the API description
(which is consistent across all usages).

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Fix indented field descriptions in PKI paths

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Clarify documentation around serial_number

Note that this field has no impact on the actual Serial Number field and
only an attribute in the requested certificate's Subject.

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Fix spelling of localdomain

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

builtin/logical/pki/fields.go

@@ -107,9 +107,11 @@ email addresses.`,
 
 	fields["serial_number"] = &framework.FieldSchema{
 		Type: framework.TypeString,
-		Description: `The requested serial number, if any. If you want
+		Description: `The Subject's requested serial number, if any.
-more than one, specify alternative names in
+See RFC 4519 Section 2.31 'serialNumber' for a description of this field.
-the alt_names map using OID 2.5.4.5.`,
+If you want more than one, specify alternative names in the alt_names
+map using OID 2.5.4.5. This has no impact on the final certificate's
+Serial Number field.`,
 	}
 
 	fields["ttl"] = &framework.FieldSchema{
@@ -127,7 +129,7 @@ be larger than the role max TTL.`,
 	fields["not_after"] = &framework.FieldSchema{
 		Type: framework.TypeString,
 		Description: `Set the not after field of the certificate with specified date value.
-                      The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ`,
+The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ`,
 	}
 
 	return fields
@@ -231,14 +233,16 @@ this value.`,
 
 	fields["serial_number"] = &framework.FieldSchema{
 		Type: framework.TypeString,
-		Description: `The requested serial number, if any. If you want
+		Description: `The Subject's requested serial number, if any.
-more than one, specify alternative names in
+See RFC 4519 Section 2.31 'serialNumber' for a description of this field.
-the alt_names map using OID 2.5.4.5.`,
+If you want more than one, specify alternative names in the alt_names
+map using OID 2.5.4.5. This has no impact on the final certificate's
+Serial Number field.`,
 	}
 	fields["not_after"] = &framework.FieldSchema{
 		Type: framework.TypeString,
 		Description: `Set the not after field of the certificate with specified date value.
-                      The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ`,
+The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ`,
 	}
 
 	return fields

builtin/logical/pki/path_fetch.go

@@ -320,9 +320,11 @@ Fetch a CA, CRL, CA Chain, or non-revoked certificate.
 `
 
 const pathFetchHelpDesc = `
-This allows certificates to be fetched. If using the fetch/ prefix any non-revoked certificate can be fetched.
+This allows certificates to be fetched. Use /cert/:serial for JSON responses.
 
 Using "ca" or "crl" as the value fetches the appropriate information in DER encoding. Add "/pem" to either to get PEM encoding.
 
 Using "ca_chain" as the value fetches the certificate authority trust chain in PEM encoding.
+
+Otherwise, specify a serial number to fetch the specified certificate. Add "/raw" to get just the certificate in DER form, "/raw/pem" to get the PEM encoded certificate.
 `

builtin/logical/pki/path_roles.go

@@ -65,7 +65,7 @@ set, defaults to the system maximum lease TTL.`,
 			"allow_localhost": {
 				Type:    framework.TypeBool,
 				Default: true,
-				Description: `Whether to allow "localhost" and "localdoamin"
+				Description: `Whether to allow "localhost" and "localdomain"
 as a valid common name in a request, independent of allowed_domains value.`,
 				DisplayAttrs: &framework.DisplayAttributes{
 					Value: true,

website/content/api-docs/secret/pki.mdx

@@ -251,7 +251,8 @@ JSON-formatted, with newlines replaced with `\n`, like so:
 ## Read CRL Configuration
 
 This endpoint allows getting the duration for which the generated CRL should be
-marked valid.
+marked valid. No CRL configuration will be returned until the configuration is
+set, but the CRL will still default to enabled with 72h expiration.
 
 | Method | Path              |
 | :----- | :---------------- |
@@ -322,7 +323,8 @@ $ curl \
 
 ## Read URLs
 
-This endpoint fetches the URLs to be encoded in generated certificates.
+This endpoint fetches the URLs to be encoded in generated certificates. No URL
+configuration will be returned until the configuration is set.
 
 | Method | Path               |
 | :----- | :----------------- |
@@ -429,9 +431,11 @@ $ curl \
 ## Rotate CRLs
 
 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
+to cut the size of the CRL if it contains a number of certificates that have
-that have now expired, but has not been rotated due to no further
+now expired, but has not been rotated due to no further certificates being
-certificates being revoked.
+revoked. If no certificates have been revoked, but the CRL has expired or is
+close to expiring, administrators must hit this endpoint to manually rotate
+the CRL.
 
 | Method | Path              |
 | :----- | :---------------- |
@@ -513,8 +517,11 @@ can be set in a CSR are supported.
 - `key_type` `(string: "rsa")` – Specifies the desired key type; must be `rsa`, `ed25519`
   or `ec`.
 
-- `key_bits` `(int: 2048)` – Specifies the number of bits to use. This must be
+- `key_bits` `(int: 0)` – Specifies the number of bits to use for the
-  changed to a valid value if the `key_type` is `ec`, e.g., 224, 256, 384 or 521.
+  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`.
 
 - `exclude_cn_from_sans` `(bool: false)` – If true, the given `common_name` will
   not be included in DNS or Email Subject Alternate Names (as appropriate).
@@ -549,9 +556,11 @@ can be set in a CSR are supported.
   subject field of the resulting CSR. This is a comma-separated string
   or JSON array.
 
-- `serial_number` `(string: "")` – Specifies the Serial Number, if any.
+- `serial_number` `(string: "")` – Specifies the requested Subject's named
-  Otherwise Vault will generate a random serial for you. If you want more than
+  [Serial Number](https://datatracker.ietf.org/doc/html/rfc4519#section-2.31)
-  one, specify alternative names in the alt_names map using OID 2.5.4.5.
+  value, if any. If you want more than one, specify alternative names in the
+  `alt_names` map using OID 2.5.4.5. Note that this has no impact on the
+  Certificate's serial number field, which Vault randomly generates.
 
 - `add_basic_constraints` `(bool: false)` – Whether to add a Basic Constraints
   extension with CA: true. Only needed as a workaround in some compatibility
@@ -950,7 +959,7 @@ request is denied.
   existing CSRs, `any` can be specified to allow keys of either type
   and with any bit size (subject to >1024 bits for RSA keys).
 
-- `key_bits` `(int: 2048)` – Specifies the number of bits to use for the
+- `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),
@@ -1242,8 +1251,11 @@ overwrite the existing cert/key with new values.
 - `key_type` `(string: "rsa")` – Specifies the desired key type; must be `rsa`, `ed25519`
   or `ec`.
 
-- `key_bits` `(int: 2048)` – Specifies the number of bits to use. This must be
+- `key_bits` `(int: 0)` – Specifies the number of bits to use for the
-  changed to a valid value if the `key_type` is `ec`, e.g., 224, 256, 384 or 521.
+  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`.
 
 - `max_path_length` `(int: -1)` – Specifies the maximum path length to encode in
   the generated certificate. `-1` means no limit. Unless the signing certificate
@@ -1289,9 +1301,11 @@ overwrite the existing cert/key with new values.
   subject field of the resulting certificate. This is a comma-separated string
   or JSON array.
 
-- `serial_number` `(string: "")` – Specifies the Serial Number, if any.
+- `serial_number` `(string: "")` –  – Specifies the default Subject's named
-  Otherwise Vault will generate a random serial for you. If you want more than
+  [Serial Number](https://datatracker.ietf.org/doc/html/rfc4519#section-2.31)
-  one, specify alternative names in the alt_names map using OID 2.5.4.5.
+  value, if any. If you want more than one, specify alternative names in the
+  `alt_names` map using OID 2.5.4.5. Note that this has no impact on the
+  Certificate's serial number field, which Vault randomly generates.
 
 - `not_after` `(string)` – Set the Not After field of the certificate with
   specified date value. The value format should be given in UTC format
@@ -1463,9 +1477,11 @@ verbatim.
   subject field of the resulting certificate. This is a comma-separated string
   or JSON array.
 
-- `serial_number` `(string: "")` – Specifies the Serial Number, if any.
+- `serial_number` `(string: "")` –  – Specifies the requested Subject's named
-  Otherwise Vault will generate a random serial for you. If you want more than
+  [Serial Number](https://datatracker.ietf.org/doc/html/rfc4519#section-2.31)
-  one, specify alternative names in the alt_names map using OID 2.5.4.5.
+  value, if any. If you want more than one, specify alternative names in the
+  `alt_names` map using OID 2.5.4.5. Note that this has no impact on the
+  Certificate's serial number field, which Vault randomly generates.
 
 - `not_after` `(string)` – Set the Not After field of the certificate with
   specified date value. The value format should be given in UTC format