From ff62a344870e0c320bc514ad04426b8a330b7cec Mon Sep 17 00:00:00 2001 From: Alexander Scheel Date: Tue, 15 Mar 2022 13:37:26 -0500 Subject: [PATCH] Update more PKI documentation (#14490) * Update description of certificate fetch API Signed-off-by: Alexander Scheel * 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 * Clarify usage of /pki/crl/rotate Signed-off-by: Alexander Scheel * 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 * Fix indented field descriptions in PKI paths Signed-off-by: Alexander Scheel * 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 * Fix spelling of localdomain Signed-off-by: Alexander Scheel --- builtin/logical/pki/fields.go | 20 +++++---- builtin/logical/pki/path_fetch.go | 4 +- builtin/logical/pki/path_roles.go | 2 +- website/content/api-docs/secret/pki.mdx | 54 ++++++++++++++++--------- 4 files changed, 51 insertions(+), 29 deletions(-) diff --git a/builtin/logical/pki/fields.go b/builtin/logical/pki/fields.go index 8618cf89b..aafae04dd 100644 --- a/builtin/logical/pki/fields.go +++ b/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 -more than one, specify alternative names in -the alt_names map using OID 2.5.4.5.`, + Description: `The Subject's requested serial number, if any. +See RFC 4519 Section 2.31 'serialNumber' for a description of this field. +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 -more than one, specify alternative names in -the alt_names map using OID 2.5.4.5.`, + Description: `The Subject's requested serial number, if any. +See RFC 4519 Section 2.31 'serialNumber' for a description of this field. +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 diff --git a/builtin/logical/pki/path_fetch.go b/builtin/logical/pki/path_fetch.go index 6bacd4adf..634964e9d 100644 --- a/builtin/logical/pki/path_fetch.go +++ b/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. ` diff --git a/builtin/logical/pki/path_roles.go b/builtin/logical/pki/path_roles.go index e788c944b..ea7dda65d 100644 --- a/builtin/logical/pki/path_roles.go +++ b/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, diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki.mdx index 5a258bbd7..9f0f921b5 100644 --- a/website/content/api-docs/secret/pki.mdx +++ b/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 -that have now expired, but has not been rotated due to no further -certificates being revoked. +to cut the size of the CRL if it contains a number of certificates that have +now expired, but has not been rotated due to no further certificates being +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 - changed to a valid value if the `key_type` is `ec`, e.g., 224, 256, 384 or 521. +- `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`. - `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. - Otherwise Vault will generate a random serial for you. If you want more than - one, specify alternative names in the alt_names map using OID 2.5.4.5. +- `serial_number` `(string: "")` – Specifies the requested Subject's named + [Serial Number](https://datatracker.ietf.org/doc/html/rfc4519#section-2.31) + 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 - changed to a valid value if the `key_type` is `ec`, e.g., 224, 256, 384 or 521. +- `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`. - `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. - Otherwise Vault will generate a random serial for you. If you want more than - one, specify alternative names in the alt_names map using OID 2.5.4.5. +- `serial_number` `(string: "")` –  – Specifies the default Subject's named + [Serial Number](https://datatracker.ietf.org/doc/html/rfc4519#section-2.31) + 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. - Otherwise Vault will generate a random serial for you. If you want more than - one, specify alternative names in the alt_names map using OID 2.5.4.5. +- `serial_number` `(string: "")` –  – Specifies the requested Subject's named + [Serial Number](https://datatracker.ietf.org/doc/html/rfc4519#section-2.31) + 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