hashivault_pki_ca – Hashicorp Vault PKI Generate Root/Intermediate

New in version 4.5.0.

Synopsis

  • WARNING: if king is intermediate and signed CSR have not been inported back to vault, module will regenerate private key and create new CSR.

  • This module generates a new private key and a CSR for signing or a new self-signed CA certificate and private key.

  • If using Vault as a root, and for many other CAs, the various parameters on the final certificate are set at signing time and may or may not honor the parameters set here.

  • This will overwrite any previously existing CA private key.

  • This is mostly meant as a helper function, and not all possible parameters that can be set in a CSR are supported.

Requirements

The below requirements are needed on the host that executes this module.

  • hvac>=0.10.1

  • ansible>=2.0.0

  • requests

Parameters

Parameter Choices/Defaults Comments
authtype
-
    Choices:
  • token
  • userpass
  • github
  • ldap
  • approle
Default:
"token or environment variable `VAULT_AUTHTYPE`"
authentication type
aws_header
-
Default:
"to environment variable `VAULT_AWS_HEADER`"
X-Vault-AWS-IAM-Server-ID Header value to prevent replay attacks.
ca_cert
-
Default:
"to environment variable `VAULT_CACERT`"
Path to a PEM-encoded CA cert file to use to verify the Vault server TLS certificate
ca_path
-
Default:
"to environment variable `VAULT_CAPATH`"
Path to a directory of PEM-encoded CA cert files to verify the Vault server TLS certificate. If ca_cert is specified, its value will take precedence
client_cert
-
Default:
"to environment variable `VAULT_CLIENT_CERT`"
Path to a PEM-encoded client certificate for TLS authentication to the Vault server
client_key
-
Default:
"to environment variable `VAULT_CLIENT_KEY`"
Path to an unencrypted PEM-encoded private key matching the client certificate
common_name
string
Specifies the requested CN for the certificate. [required]
config
dictionary
Collection of properties for pki generate root. Ref. https://www.vaultproject.io/api-docs/secret/pki#generate-root
alt_names
string
Specifies the requested Subject Alternative Names, in a comma-delimited list.
These can be host names or email addresses; they will be parsed into their respective fields.
country
list
Specifies the `C` (Country) values in the subject field of the resulting certificate.
exclude_cn_from_sans
boolean
    Choices:
  • no ←
  • yes
If set, the given `common_name` will not be included in DNS or Email Subject Alternate Names (as appropriate).
Useful if the CN is not a hostname or email address, but is instead some human-readable identifier.
format
string
Default:
"pem"
Specifies the format for returned data.
If `der`, the output is base64 encoded.
If `pem_bundle`, the `certificate` field will contain the private key (if exported) and certificate, concatenated;
if the issuing CA is not a Vault-derived self-signed root, this will be included as well.
ip_sans
string
Specifies the requested IP Subject Alternative Names, in a comma-delimited list.
key_bits
integer
Default:
2048
Specifies the number of bits to use
key_type
string
Default:
"rsa"
Specifies the desired key type.
locality
list
Specifies the `L` (Locality) values in the subject field of the resulting certificate.
max_path_length
integer
Default:
-1
Specifies the maximum path length to encode in the generated certificate.
A limit of `-1` means no limit.
Unless the signing certificate has a maximum path length set, in which case the path length is set to one less than that of the signing certificate.
A limit of `0` means a literal path length of zero.
organization
list
Specifies the `O` (Organization) values in the subject field of the resulting certificate.
other_sans
string
Specifies custom OID/UTF8-string SANs.
These must match values specified on the role in `allowed_other_sans` (see role creation for allowed_other_sans globbing rules).
The format is the same as OpenSSL `<oid>;<type>:<value>` where the only current valid type is `UTF8`
This can be a comma-delimited list or a JSON string slice.
ou
list
Specifies the `OU` (OrganizationalUnit) values in the subject field of the resulting certificate.
permitted_dns_domains
list
A list containing DNS domains for which certificates are allowed to be issued or signed by this CA certificate.
Note that subdomains are allowed, as per https://tools.ietf.org/html/rfc5280#section-4.2.1.10.
postal_code
list
Specifies the Postal Code values in the subject field of the resulting certificate.
private_key_format
string
Default:
"der"
Specifies the format for marshaling the private key.
Defaults to `der` which will return either base64-encoded DER or PEM-encoded DER, depending on the value of `format`.
The other option is `pkcs8` which will return the key marshalled as PEM-encoded PKCS8
province
list
Specifies the `ST` (Province) values in the subject field of the resulting certificate.
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.
street_address
list
Specifies the Street Address values in the subject field of the resulting certificate.
ttl
string
Specifies the requested Time To Live (after which the certificate will be expired).
This cannot be larger than the engine's max (or, if not set, the system max).
uri_sans
string
Specifies the requested URI Subject Alternative Names, in a comma-delimited list.
kind
string
    Choices:
  • root ←
  • intermediate
Specifies the kind of CA certificate.
login_mount_point
-
Default:
"value of authtype or environment varialbe `VAULT_LOGIN_MOUNT_POINT`"
authentication mount point
mount_point
-
Default:
"pki"
location where secrets engine is mounted. also known as path
namespace
-
Default:
"to environment variable VAULT_NAMESPACE"
namespace for vault
password
-
Default:
"to environment variable `VAULT_PASSWORD`"
password to login to vault.
state
string
    Choices:
  • present ←
  • absent
Do you want for this config to be present or absent
token
-
Default:
"to environment variable `VAULT_TOKEN`"
token for vault
type
string
    Choices:
  • exported
  • internal ←
Specifies the type of the root to create, If `exported`, the private key will be returned in the response;
If it is `internal` the private key will not be returned and cannot be retrieved later.
url
-
Default:
"to environment variable `VAULT_ADDR`"
url for vault
username
-
Default:
"to environment variable `VAULT_USER`"
username to login to vault.
verify
-
Default:
"to environment variable `VAULT_SKIP_VERIFY`"
If set, do not verify presented TLS certificate before communicating with Vault server. Setting this variable is not recommended except during testing

Examples

---
- hosts: localhost
  tasks:
    - name: Delete Root
      hashivault_pki_ca:
        common_name: my common name

Status

Authors

  • UNKNOWN

Hint

If you notice any issues in this documentation, you can edit this document to improve it.