luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

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>
This commit is contained in:
Alexander Scheel 2022-03-15 13:37:26 -05:00 committed by GitHub
parent d222981cec
commit ff62a34487
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 51 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
builtin/logical/pki/fields.go
View File

@ -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{
@ -231,9 +233,11 @@ 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,

4
builtin/logical/pki/path_fetch.go
View File

@ -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.
`

2
builtin/logical/pki/path_roles.go
View File

@ -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,

54
website/content/api-docs/secret/pki.mdx
View File

@ -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