From fb731c06dc5677f54e3d5504ee36358fb300d579 Mon Sep 17 00:00:00 2001 From: aefuente Date: Thu, 16 Oct 2025 16:21:12 -0500 Subject: [PATCH 1/2] role configuration table --- README.md | 2 ++ docs/role_options.md | 46 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 docs/role_options.md diff --git a/README.md b/README.md index fbb5cf4..1dde9ee 100644 --- a/README.md +++ b/README.md @@ -462,6 +462,8 @@ kftrain.lab". These properties can also be set in the certificate template configured in Command. If they differ, the most restrictive setting is applied. +Here is a table of [Role Configuration Options](./docs/role_options.md) + ## Using the plugin ### Issuing Certificates diff --git a/docs/role_options.md b/docs/role_options.md new file mode 100644 index 0000000..c817395 --- /dev/null +++ b/docs/role_options.md @@ -0,0 +1,46 @@ +# Role Options + +`vault write keyfactor/roles/ =""` + +Here is a table of the available configuration parameters + +| name | value type | required | default | description | +| ---- | ----------- | -------- | -------- | ----------- | +| ttl | duration (seconds) | false | | The lease duration if no specific lease duration is requested. The lease duration controls the expiration of certificates issued by this backend. Defaults to the value of max_ttl. | +| max_ttl | duration (seconds) | false | | The maximum allowed lease duration | +| allow_localhost | bool | false | true | Whether to allow "localhost" as a valid common name in a request | +| allowed_domains | string slice (comma-separated) | false | | If set, clients can request certificates for subdomains directly beneath these domains, including the wildcard subdomains. Accepts a comma-separated string or list of domains. | +| allowed_domains_template | bool | false | false | If set, allowed domains can be specified using identity template policies. Non-templated domains are also permitted. | +| allow_bare_domains | bool | false | | If set, clients can request certificates for the base domains themselves, e.g. "example.com". In some cases this can be considered a security threat. | +| allow_subdomains | bool | false | | If set, clients can request certificates for subdomains of the CNs allowed by the other role options, including wildcard subdomains. | +| allow_glob_domains | bool | false | | If set, domains specified in "allowed_domains" can include glob patterns, e.g. "ftp*.example.com". | +| allow_any_name | bool | false | | If set, clients can request certificates for any CN they like. | +| enforce_hostnames | bool | false | true | If set, only valid host names are allowed for CN and SANs. Defaults to true. | +| allow_ip_sans | bool | false | true | If set, IP Subject Alternative Names are allowed. Any valid IP is accepted. | +| allowed_uri_sans | string slice (comma-separated) | false | | If set, an array of allowed URIs to put in the URI Subject Alternative Names. Any valid URI is accepted; supports globbing. | +| allowed_other_sans | string slice (comma-separated) | false | | If set, an array of allowed other names to put in SANs. Values support globbing and must be in the format `;:`. Only "utf8" is a valid type. | +| allowed_serial_numbers | string slice (comma-separated) | false | | If set, an array of allowed serial numbers to put in Subject. Values support globbing. | +| server_flag | bool | false | true | If set, certificates are flagged for server auth use. Defaults to true. | +| client_flag | bool | false | true | If set, certificates are flagged for client auth use. Defaults to true. | +| code_signing_flag | bool | false | | If set, certificates are flagged for code signing use. Defaults to false. | +| email_protection_flag | bool | false | | If set, certificates are flagged for email protection use. Defaults to false. | +| key_type | string | false | rsa | The type of key to use; defaults to RSA. Valid values: "rsa", "ec". | +| key_bits | int | false | 2048 | The number of bits to use. You may want to change this if you adjust key_type. | +| key_usage | string slice (comma-separated) | false | DigitalSignature, KeyAgreement, KeyEncipherment | A list of key usages (not extended). To remove all, set to an empty list. | +| ext_key_usage | string slice (comma-separated) | false | [] | A list of extended key usages. To remove all, set to an empty list. | +| ext_key_usage_oids | string slice (comma-separated) | false | | A list of extended key usage OIDs. | +| use_csr_common_name | bool | false | true | If set, when used with a signing profile, the CN in the CSR will be used. Defaults to true. | +| use_csr_sans | bool | false | true | If set, when used with a signing profile, the SANs in the CSR will be used. Defaults to true. | +| ou | string slice (comma-separated) | false | | If set, OU (OrganizationalUnit) will be set to this value in issued certificates. | +| organization | string slice (comma-separated) | false | | If set, O (Organization) will be set to this value in issued certificates. | +| country | string slice (comma-separated) | false | | If set, Country will be set to this value in issued certificates. | +| locality | string slice (comma-separated) | false | | If set, Locality will be set to this value in issued certificates. | +| province | string slice (comma-separated) | false | | If set, Province will be set to this value in issued certificates. | +| street_address | string slice (comma-separated) | false | | If set, Street Address will be set to this value in issued certificates. | +| postal_code | string slice (comma-separated) | false | | If set, Postal Code will be set to this value in issued certificates. | +| generate_lease | bool | false | | If set, certificates issued against this role will have Vault leases attached to them. Recommended to disable when issuing many long-lived certs. | +| no_store | bool | false | | If set, certificates issued against this role will not be stored in the backend. Improves performance but prevents revocation/enumeration. | +| require_cn | bool | false | true | If false, makes the 'common_name' field optional when generating a certificate. | +| policy_identifiers | string slice (comma-separated) | false | | A list of policy OIDs. | +| basic_constraints_valid_for_non_ca | bool | false | | Mark Basic Constraints valid when issuing non-CA certificates. | +| not_before_duration | duration (seconds) | false | 30 | The duration before now the certificate should be considered valid (creation offset). | From bdb4559fb0afbef8a4d3658194555b651ea9fe75 Mon Sep 17 00:00:00 2001 From: aefuente Date: Thu, 16 Oct 2025 16:36:42 -0500 Subject: [PATCH 2/2] adjust names for types --- docs/role_options.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/role_options.md b/docs/role_options.md index c817395..6f600a4 100644 --- a/docs/role_options.md +++ b/docs/role_options.md @@ -1,15 +1,15 @@ # Role Options -`vault write keyfactor/roles/ =""` +`vault write keyfactor/roles/hashiwebserver =""` Here is a table of the available configuration parameters | name | value type | required | default | description | | ---- | ----------- | -------- | -------- | ----------- | -| ttl | duration (seconds) | false | | The lease duration if no specific lease duration is requested. The lease duration controls the expiration of certificates issued by this backend. Defaults to the value of max_ttl. | -| max_ttl | duration (seconds) | false | | The maximum allowed lease duration | +| ttl | number (seconds) | false | | The lease duration if no specific lease duration is requested. The lease duration controls the expiration of certificates issued by this backend. Defaults to the value of max_ttl. | +| max_ttl | number (seconds) | false | | The maximum allowed lease duration | | allow_localhost | bool | false | true | Whether to allow "localhost" as a valid common name in a request | -| allowed_domains | string slice (comma-separated) | false | | If set, clients can request certificates for subdomains directly beneath these domains, including the wildcard subdomains. Accepts a comma-separated string or list of domains. | +| allowed_domains | list (comma-separated) | false | | If set, clients can request certificates for subdomains directly beneath these domains, including the wildcard subdomains. Accepts a comma-separated string or list of domains. | | allowed_domains_template | bool | false | false | If set, allowed domains can be specified using identity template policies. Non-templated domains are also permitted. | | allow_bare_domains | bool | false | | If set, clients can request certificates for the base domains themselves, e.g. "example.com". In some cases this can be considered a security threat. | | allow_subdomains | bool | false | | If set, clients can request certificates for subdomains of the CNs allowed by the other role options, including wildcard subdomains. | @@ -17,30 +17,30 @@ Here is a table of the available configuration parameters | allow_any_name | bool | false | | If set, clients can request certificates for any CN they like. | | enforce_hostnames | bool | false | true | If set, only valid host names are allowed for CN and SANs. Defaults to true. | | allow_ip_sans | bool | false | true | If set, IP Subject Alternative Names are allowed. Any valid IP is accepted. | -| allowed_uri_sans | string slice (comma-separated) | false | | If set, an array of allowed URIs to put in the URI Subject Alternative Names. Any valid URI is accepted; supports globbing. | -| allowed_other_sans | string slice (comma-separated) | false | | If set, an array of allowed other names to put in SANs. Values support globbing and must be in the format `;:`. Only "utf8" is a valid type. | -| allowed_serial_numbers | string slice (comma-separated) | false | | If set, an array of allowed serial numbers to put in Subject. Values support globbing. | +| allowed_uri_sans | list (comma-separated) | false | | If set, an array of allowed URIs to put in the URI Subject Alternative Names. Any valid URI is accepted; supports globbing. | +| allowed_other_sans | list (comma-separated) | false | | If set, an array of allowed other names to put in SANs. Values support globbing and must be in the format `;:`. Only "utf8" is a valid type. | +| allowed_serial_numbers | list (comma-separated) | false | | If set, an array of allowed serial numbers to put in Subject. Values support globbing. | | server_flag | bool | false | true | If set, certificates are flagged for server auth use. Defaults to true. | | client_flag | bool | false | true | If set, certificates are flagged for client auth use. Defaults to true. | | code_signing_flag | bool | false | | If set, certificates are flagged for code signing use. Defaults to false. | | email_protection_flag | bool | false | | If set, certificates are flagged for email protection use. Defaults to false. | | key_type | string | false | rsa | The type of key to use; defaults to RSA. Valid values: "rsa", "ec". | -| key_bits | int | false | 2048 | The number of bits to use. You may want to change this if you adjust key_type. | -| key_usage | string slice (comma-separated) | false | DigitalSignature, KeyAgreement, KeyEncipherment | A list of key usages (not extended). To remove all, set to an empty list. | -| ext_key_usage | string slice (comma-separated) | false | [] | A list of extended key usages. To remove all, set to an empty list. | -| ext_key_usage_oids | string slice (comma-separated) | false | | A list of extended key usage OIDs. | +| key_bits | number | false | 2048 | The number of bits to use. You may want to change this if you adjust key_type. | +| key_usage | list (comma-separated) | false | DigitalSignature, KeyAgreement, KeyEncipherment | A list of key usages (not extended). To remove all, set to an empty list. | +| ext_key_usage | list (comma-separated) | false | [] | A list of extended key usages. To remove all, set to an empty list. | +| ext_key_usage_oids | list (comma-separated) | false | | A list of extended key usage OIDs. | | use_csr_common_name | bool | false | true | If set, when used with a signing profile, the CN in the CSR will be used. Defaults to true. | | use_csr_sans | bool | false | true | If set, when used with a signing profile, the SANs in the CSR will be used. Defaults to true. | -| ou | string slice (comma-separated) | false | | If set, OU (OrganizationalUnit) will be set to this value in issued certificates. | -| organization | string slice (comma-separated) | false | | If set, O (Organization) will be set to this value in issued certificates. | -| country | string slice (comma-separated) | false | | If set, Country will be set to this value in issued certificates. | -| locality | string slice (comma-separated) | false | | If set, Locality will be set to this value in issued certificates. | -| province | string slice (comma-separated) | false | | If set, Province will be set to this value in issued certificates. | -| street_address | string slice (comma-separated) | false | | If set, Street Address will be set to this value in issued certificates. | -| postal_code | string slice (comma-separated) | false | | If set, Postal Code will be set to this value in issued certificates. | +| ou | list (comma-separated) | false | | If set, OU (OrganizationalUnit) will be set to this value in issued certificates. | +| organization | list (comma-separated) | false | | If set, O (Organization) will be set to this value in issued certificates. | +| country | list (comma-separated) | false | | If set, Country will be set to this value in issued certificates. | +| locality | list (comma-separated) | false | | If set, Locality will be set to this value in issued certificates. | +| province | list (comma-separated) | false | | If set, Province will be set to this value in issued certificates. | +| street_address | list (comma-separated) | false | | If set, Street Address will be set to this value in issued certificates. | +| postal_code | list (comma-separated) | false | | If set, Postal Code will be set to this value in issued certificates. | | generate_lease | bool | false | | If set, certificates issued against this role will have Vault leases attached to them. Recommended to disable when issuing many long-lived certs. | | no_store | bool | false | | If set, certificates issued against this role will not be stored in the backend. Improves performance but prevents revocation/enumeration. | | require_cn | bool | false | true | If false, makes the 'common_name' field optional when generating a certificate. | -| policy_identifiers | string slice (comma-separated) | false | | A list of policy OIDs. | +| policy_identifiers | list (comma-separated) | false | | A list of policy OIDs. | | basic_constraints_valid_for_non_ca | bool | false | | Mark Basic Constraints valid when issuing non-CA certificates. | -| not_before_duration | duration (seconds) | false | 30 | The duration before now the certificate should be considered valid (creation offset). | +| not_before_duration | number (seconds) | false | 30 | The duration before now the certificate should be considered valid (creation offset). |