vault PKI secrets engine Certificate Management Protocol v2 CMPv2 EnterpriseAlert inline true page title Certificate Management Protocol v2 CMPv2 within Vault PKI Secrets Engines This document summarizes Vault s PKI Secrets Engine layout docs implementation of the CMPv2 protocol https datatracker ietf org doc html rfc4210 EnterpriseAlert inline true An overview of the Certificate Management Protocol v2 implementation within Vault

Answer:
---
layout: docs
page_title: Certificate Management Protocol v2 (CMPv2) within Vault | PKI - Secrets Engines
description: An overview of the Certificate Management Protocol (v2) implementation within Vault.
---

# PKI secrets engine - Certificate Management Protocol v2 (CMPv2) <EnterpriseAlert inline="true" />

This document summarizes Vault's PKI Secrets Engine
implementation of the [CMPv2 protocol](https://datatracker.ietf.org/doc/html/rfc4210) <EnterpriseAlert inline="true" />,
its configuration, and limitations.

## What is Certificate Management Protocol v2 (CMPv2)?

The CMP protocol is an IETF standardized protocol, [RFC 4210](https://datatracker.ietf.org/doc/html/rfc4210),
that allows clients to acquire client certificates and their associated Certificate
Authority (CA) certficates.

## Enabling CMPv2 support on a Vault PKI mount

To configure an existing mount to serve CMPv2 clients, the following steps are
required, which are broken down into three main categories:

 1. [Configuring an Issuer](#configuring-an-issuer)
 1. [Authentication mechanisms](#configuring-cmpv2-authentication)
 1. [Updating PKI tunable parameters](#updating-the-pki-mount-tunable-parameters)
 1. [PKI CMPv2 configuration](#enabling-cmpv2)

### Configuring an Issuer

CMPv2 is a bit unique, in that it uses the Issuer CA certificate to sign the
CMP messages.  This means your issuer must have the `DigitalSignature` key
usage.
Existing CA issuers likely do not have this, so you will need to generate a new
issuer (likely an intermediate) that has this property.  If you are configuring PKI
for the first time or creating a new issuer, ensure you set `key_usage` to,
as an example, `CRL,CASign,DigitalSignature`.

See [Generate intermediate CSR](/vault/api-docs/secret/pki#generate-intermediate-csr)

### Configuring CMPv2 Authentication

At this time, Vault's implementation of CMPv2 supports only
[Certificate TLS authentication](/vault/docs/auth/cert), where clients proof
of posession of a TLS client certificate authenticates them to Vault.

Authentication leverages a separate Vault authentication
mount, within the same namespace, to validate the client provided credentials
along with the client's ACL policy to enforce.

For proper accounting, a mount supporting CMPv2 authentication should be
dedicated to this purpose, not shared with other workflows.  In other words,
create a new certificate auth mount for CMPv2 even if you already have one
another in use for other purposes.

When setting up the authentication mount for CMPv2 clients, the token type must
be configured to return [batch tokens](/vault/docs/concepts/tokens#batch-tokens).
Batch tokens are required to avoid an excessive amount of leases being generated
and persisted as every CMPv2 incoming request needs to be authenticated.

The path within an ACL policy must match the `cmp` path underneath the
PKI mount.  The path to use can be the default `cmp` path or a role based one.

If using the `sign-verbatim` as a path policy, the following
ACL policy will allow an authenticated client access the required PKI CMP path.
```
path “pki/cmp” {
  capabilities=[“update”, “create”]
}
```

For a role base path policy, this sample policy can be used
```
path “pki/roles/my-role-name/cmp” {
  capabilities=[“update”, “create”]
}
```

#### Updating the PKI mount tunable parameters

Once the authentication mount has been created and configured, the authentication mount's accessor
will need to be captured and added within the PKI mount's [delegated auth accessors](/vault/api-docs/system/mounts#delegated_auth_accessors).

To get an authentication mount's accessor field, the following command can be used.

```shell-session
$ vault read -field=accessor sys/auth/auth/cert
```

For CMP to work within certain clients, a few response headers need to be explicitly
allowed, trailing slashes must be trimmed, and the list of accessors the mount can delegate authentication towards
must be configured. The following will grant the required response headers, you will need to replace the values for
the `delegated-auth-accessors` to match your values.

```shell-session
$ vault secrets tune \
  -allowed-response-headers="Content-Transfer-Encoding" \
  -allowed-response-headers="Content-Length" \
  -allowed-response-headers="WWW-Authenticate" \
  -delegated-auth-accessors="auth_cert_4088ac2d" \
  -trim-request-trailing-slashes="true" \
  pki
```

#### Enabling CMPv2

Enabling CMP is a matter of writing to the `config/cmp` endpoint, to set it
enabled and configure default path policy and authentication.

```shell-session
vault write pki/config/cmp -<<EOC
{
  "enabled": true,
  "default_path_policy": "role:example-role",
  "authenticators": {
    "cert": {
      "accessor": "auth_cert_4088ac2d"
    }
  },
  "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"]
}
EOC
```

Of course, substituting your own role and accessor values.  After this, the
CMP endpoints will be able to handle client requests, authenticated with the
previously configured Cert Auth method.

## Limitations

The initial release of CMPv2 support is intentionally limited to a subset of the
protocol, covering Initialization, Certification, and Key Update, over HTTP.
In particular, the following are not yet supported:

 * Basic authentication scheme using PasswordBasedMac
 * Revocation
 * CRL fetching via CMP itself.
 * CA creation/update operations.

Note that CMPv2 is not integrated with these existing Vault PKI features:

 * Certificate Metadata - CMPv2 has no means of providing metadata.
 * Certificate Issuance External Policy Service [(CIEPS)](/vault/docs/secrets/pki/cieps)

layout  docs page title  Certificate Management Protocol v2  CMPv2  within Vault   PKI   Secrets Engines description  An overview of the Certificate Management Protocol  v2  implementation within Vault         PKI secrets engine   Certificate Management Protocol v2  CMPv2   EnterpriseAlert inline  true      This document summarizes Vault s PKI Secrets Engine implementation of the  CMPv2 protocol  https   datatracker ietf org doc html rfc4210   EnterpriseAlert inline  true      its configuration  and limitations      What is Certificate Management Protocol v2  CMPv2    The CMP protocol is an IETF standardized protocol   RFC 4210  https   datatracker ietf org doc html rfc4210   that allows clients to acquire client certificates and their associated Certificate Authority  CA  certficates      Enabling CMPv2 support on a Vault PKI mount  To configure an existing mount to serve CMPv2 clients  the following steps are required  which are broken down into three main categories    1   Configuring an Issuer   configuring an issuer   1   Authentication mechanisms   configuring cmpv2 authentication   1   Updating PKI tunable parameters   updating the pki mount tunable parameters   1   PKI CMPv2 configuration   enabling cmpv2       Configuring an Issuer  CMPv2 is a bit unique  in that it uses the Issuer CA certificate to sign the CMP messages   This means your issuer must have the  DigitalSignature  key usage  Existing CA issuers likely do not have this  so you will need to generate a new  issuer  likely an intermediate  that has this property   If you are configuring PKI  for the first time or creating a new issuer  ensure you set  key usage  to  as an example   CRL CASign DigitalSignature    See  Generate intermediate CSR   vault api docs secret pki generate intermediate csr       Configuring CMPv2 Authentication  At this time  Vault s implementation of CMPv2 supports only   Certificate TLS authentication   vault docs auth cert   where clients proof of posession of a TLS client certificate authenticates them to Vault   Authentication leverages a separate Vault authentication mount  within the same namespace  to validate the client provided credentials along with the client s ACL policy to enforce    For proper accounting  a mount supporting CMPv2 authentication should be dedicated to this purpose  not shared with other workflows   In other words  create a new certificate auth mount for CMPv2 even if you already have one  another in use for other purposes   When setting up the authentication mount for CMPv2 clients  the token type must be configured to return  batch tokens   vault docs concepts tokens batch tokens   Batch tokens are required to avoid an excessive amount of leases being generated and persisted as every CMPv2 incoming request needs to be authenticated   The path within an ACL policy must match the  cmp  path underneath the  PKI mount   The path to use can be the default  cmp  path or a role based one   If using the  sign verbatim  as a path policy  the following ACL policy will allow an authenticated client access the required PKI CMP path      path  pki cmp      capabilities   update    create          For a role base path policy  this sample policy can be used     path  pki roles my role name cmp      capabilities   update    create               Updating the PKI mount tunable parameters  Once the authentication mount has been created and configured  the authentication mount s accessor will need to be captured and added within the PKI mount s  delegated auth accessors   vault api docs system mounts delegated auth accessors    To get an authentication mount s accessor field  the following command can be used      shell session   vault read  field accessor sys auth auth cert      For CMP to work within certain clients  a few response headers need to be explicitly allowed  trailing slashes must be trimmed  and the list of accessors the mount can delegate authentication towards must be configured  The following will grant the required response headers  you will need to replace the values for  the  delegated auth accessors  to match your values      shell session   vault secrets tune      allowed response headers  Content Transfer Encoding       allowed response headers  Content Length       allowed response headers  WWW Authenticate       delegated auth accessors  auth cert 4088ac2d       trim request trailing slashes  true      pki           Enabling CMPv2  Enabling CMP is a matter of writing to the  config cmp  endpoint  to set it enabled and configure default path policy and authentication      shell session vault write pki config cmp    EOC      enabled   true     default path policy    role example role      authenticators          cert            accessor    auth cert 4088ac2d                audit fields     common name    alt names    ip sans    uri sans     EOC      Of course  substituting your own role and accessor values   After this  the CMP endpoints will be able to handle client requests  authenticated with the  previously configured Cert Auth method      Limitations  The initial release of CMPv2 support is intentionally limited to a subset of the protocol  covering Initialization  Certification  and Key Update  over HTTP  In particular  the following are not yet supported      Basic authentication scheme using PasswordBasedMac    Revocation    CRL fetching via CMP itself     CA creation update operations   Note that CMPv2 is not integrated with these existing Vault PKI features       Certificate Metadata   CMPv2 has no means of providing metadata     Certificate Issuance External Policy Service   CIEPS    vault docs secrets pki cieps


vault The PKI secrets engine for Vault generates TLS certificates layout docs Since Vault 1 11 0 Vault s PKI Secrets Engine supports multiple issuers in a single mount point By using the certificate types below rotation can be page title PKI Secrets Engine Rotation Primitives PKI secrets engine rotation primitives

Answer:
---
layout: docs
page_title: 'PKI - Secrets Engine: Rotation Primitives'
description: The PKI secrets engine for Vault generates TLS certificates.
---

# PKI secrets engine - rotation primitives

Since Vault 1.11.0, Vault's PKI Secrets Engine supports multiple issuers in a
single mount point. By using the certificate types below, rotation can be
accomplished in various situations involving both root and intermediate CAs
managed by Vault.

## X.509 certificate fields

X.509 is a complex specification; modern implementations tend to refer to
[RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280) for specific
details. For validation of certificates, both RFC 5280 and the TLS
validation [RFC 6125](https://datatracker.ietf.org/doc/html/rfc6125) are
important for understanding how to achieve rotation.

The following is a simplification of these standards for the purpose of
this document.

Every X.509 certificate begins with an asymmetric key pair, using an algorithm
like RSA or ECDSA. This key pair is used to create a Certificate Signing
Request (CSR), which contains a set of fields the requester would like in the
final certificate (but, it is up to the Certificate Authority (CA) to decide what
fields to take from the CSR and which to override). The CSR also contains the
public key of the pair, which is signed by the private key of the key pair to
prove possession. Usually, the requester would ask for attributes in the
Subject field of the CSR or in the Subject Alternative Name extension CSR to
be respected in the final certificate. It is up to the CA if these values are
trusted or not. When approved by the issuing authority (which may be backed by
this asymmetric key itself in the case of a root self-signed certificate), the
authority attaches the Subject of _its_ certificate to the issued certificate in
the Issuer field, assigns a unique serial number to the issued certificate, and
signs the set of fields with its private key, thus creating the certificate.

There are some important restrictions here:

 - One certificate can only have one Issuer, but this issuer is identified by
   the Subject on the issuing certificate and its public key.
 - One key pair can be used for multiple certificates, but one certificate can
   only have one backing key material.

The following fields on the final certificate are relevant to rotation:

 - The backing [public](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.7)
   and private key material (Subject Public Key Info).
   - Note that the private key is not included in the certificate but is
     uniquely determined by the public key material.
 - The [Subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the certificate.
   - This identifies the entity to which the certificate was issued. While the
     SAN values (in the [Subject Alternative Name](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.6)
     extension) is useful when validating TLS Server certificates against the
     negotiated hostname and URI, it isn't generally relevant for the purposes
     of validating intermediate certificate chains or in rotation.
 - The [Validity](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.5)
   period of this certificate.
   - Notably, RFC 5280 does not place any requirements around the issued
     certificate's validity period relative to the validity period of the
     issuing certificate. However, it [does state](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.5)
     that certificates ought to be revoked if their status cannot be maintained
     up to their notAfter date. This is why Vault 1.11's `/pki/issuer/:issuer_ref`
     configuration endpoint maintains the `leaf_not_after_behavior` per-issuer
     rather than per-role.
   - Additionally, some browsers will place ultimate trust in the certificates
     in their trust stores, even when these certificates are expired.
     - Note that this only applies to certificates in the trust store; validity
       periods will still be enforced for certificates not in the store (such
       as intermediates).
 - The [Issuer](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.4) and
   [signatureValue](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.1.3)
   of this certificate.
   - In the issued certificate's Issuer field, the issuing certificate places
     its own Subject value. This allows the issuer to be identified later
     (without having to try signature validation against every known local
     certificate), when validating the presented certificate and chain.
   - The signature over the entire certificate (by the issuer's private key)
     is then placed in the signatureValue field.
 - The optional [Authority Key Identifier](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.1)
   field.
   - This field can contain either (or both) of two values:
     - The hash of the issuer's public key. This extension is set and this
       value is filled in by Vault.
     - The Issuer's Subject and Serial Number. This value is not set by Vault.
   - The latter is a dangerous restriction for the purposes of rotation: it
     prevents cross-signing and reissuance as the new issuing certificates
     (while having the same backing key material) will have different serial
     numbers. See the [Limitations of Primitives](#limitations-of-primitives)
     section below for more information on this restriction.
 - The [Serial Number](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.2)
   of this certificate.
   - This field is unique to a specific issuer; when a certificate is
     reissued by its parent authority, it will always have a different serial
     number field.
 - The [CRL distribution](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.13)
   point field.
   - This is a field detailing where a CRL is expected to exist for this
     certificate and under which CRL issuers (defaulting to the issuing
     certificate itself) the CRL is expected to be signed by. This is mostly
     informational and for server software like nginx, Vault's Cert Auth method,
     and Apache, CRLs are provided to the server, rather than having the
     server fetch CRLs for certificates automatically.
   - Note that root certificates (in browsers trust stores) are generally not
     considered revocable. However, if an intermediate is revoked by serial,
     it will appear on its parent's CRL, and may prevent rotation from
     happening.

## X.509 rotation primitives

Rotation (from an organizational standpoint) can only safely happen with
certain intermediate X.509 certificates being issued. To distinguish the two
types of certificates used to achieve rotation, this document notates them
as _primitives_.

Rotation of an end-entity certificate is trivial from an X.509 trust chain
perspective; this process happens every day and should only depend on what is
in the trust store and not the end-entity certificate itself. In Vault, the
requester would hit the various issuance endpoints (`/pki/issue/:name` or
`/pki/sign/:name` -- or use the unsafe `/pki/sign-verbatim`) and swap out the
old certificate with the new certificate and reload the configuration or
restart the service. Other parts of the organizations might use
[ACME](https://datatracker.ietf.org/doc/html/rfc8555) for certificate issuance
and rotation, especially if the service is public-facing (and thus needs to
be issued by a Public CA). Given it was signed by a trusted root, any devices
connecting to the service would not know the difference.

Rotation of intermediate certificates is almost as easy. Assuming a decent
operational setup (wherein during end-entity issuance, the full certificate
chain is updated in the service's configuration), this should be as easy as
creating a new intermediate CA, signing it against the root CA, and then
beginning issuance against the new intermediate certificate. In Vault, if
the intermediate is generated in an existing mount path (or is moved into
such), the requesting entity shouldn't care much. Under ACME, Let's Encrypt
has successfully rotated intermediates to present a cross-signed chain
([for older Android devices](https://letsencrypt.org/2020/12/21/extending-android-compatibility.html)).
Assuming the old intermediate's parent(s) are still valid and trusted,
certificates issued under old intermediates should continue to validate.

The hard part of rotation--calling for the use of these primitives--is
rotating root certificates. These live in every device's trust store and
are hard to update from an organization-wide operational perspective.
Unless the organization can swap out roots almost instantaneously and
simultaneously (e.g., via an agent) with no missed devices, this process
will likely span months.

To make this process lower risk, there are various primitive certificate
types that use the [above certificate fields](#x-509-certificate-fields).
Key to their success is the following note:

~> Note: While certificates are added to the trust store, it is ultimately
   the associated key material that determines trust: two issuer certificates
   with the same subject but different public keys cannot validate the same
   leaf certificate; only if the keys are the same can this occur.

### Cross-Signed primitive

This is the most common type of rotation primitive. A common CSR is signed by
two CAs, resulting in two certificates. These certificates must have the same
Subject (but may have different Issuers and will have different Serial Numbers)
and the same backing key material, to allow certificates they sign to be
trusted by either variant.

Note that, due to restrictions in how end-entity certificates are used and
validated (services and validation libraries expect only one), cross-signing
most typically only applies to intermediate.

#### A note on Cross-Signed roots

Technically, cross-signing can occur between two roots, allowing trust bundles
with either root to validate certs issued through the other. However, this
process creates a certificate that is effectively an intermediate (as it is
no longer self-signed) and usually must be served alongside the trust chain.
Given this restriction, it's preferable to instead cross-sign the top-level
intermediates under the root unless strictly necessary when the old root
certificate has been used to directly issue leaf certificates.

So, the rest of this process flow assumes an intermediate is being
cross-signed as this is more common.

##### Process flow

```
        -------------------
       | generate key pair | -------------> ...
        -------------------                 ...
           |            |                   ...
 --------------        --------------       ...
| generate CSR |      | generate CSR |      ...
 --------------        --------------       ...
         |                   |              ...
    -----------         -----------         ...
   | signed by |       | signed by |        ...
   | root A    |       | root B    |        ...
    -----------         -----------         ...
```

Here, a key pair was generated at some point in time. Two CSRs are created and
sent to two different root authorities (Root A and Root B). These result in two
separate certificates (potentially with different validity periods) with the
same Subject and same backing key material.

Note that this cross-signing need not happen simultaneously; there could be a
gap of several years between the first and second certificate. Additionally,
there's no limit on the number of cross-signed "duplicate" (used loosely--with
the same subject and key material) certificates: this could be cross-signed
by many different root certificates if necessary and desired.

##### Certificate hierarchy

```
 --------                                            --------
| root A |                                          | root B |
 --------                                            --------
   |                                                      |
 ----------------                            ----------------
| intermediate C |  <- same key material -> | intermediate D |
 ----------------              |             ----------------
                               |
                      -------------------
                     | leaf certificates |
                      -------------------
```

The above process results in two trust paths: either of root A or root B (or
both) could exist in the client's trust stores and the leaf certificate would
validate correctly. Because the same key material is used for both intermediate
certificates (C and D), the issued leaf certificate's signature field would
be the same regardless of which intermediate was contacted.

Cross-signing is thus a unifying primitive; two separate trust paths now join
into a single one, by having leaf certificate's issuer field to point to two
separate paths (via duplication of the certificate in the chain) and would be
conditionally validated based on which root is present in the trust store.

This construct is documented and used in several places:

 - https://letsencrypt.org/certificates/
 - https://scotthelme.co.uk/cross-signing-alternate-trust-paths-how-they-work/
 - https://security.stackexchange.com/questions/14043/what-is-the-use-of-cross-signing-certificates-in-x-509

#### Execution in Vault

To create a cross-signed certificate in Vault, use the [`/intermediate/cross-sign`
endpoint](/vault/api-docs/secret/pki#generate-intermediate-csr). Here, when creating
a cross-signature to all `cert B` to be validated by `cert A`, provide the values
(`key_ref`, all Subject parts, &c) for `cert B` during intermediate generation.
Then sign this CSR (using the [`/issuer/:issuer_ref/sign-intermediate`
endpoint](/vault/api-docs/secret/pki#sign-intermediate)) with `cert A`'s reference
and provide necessary values from `cert B` (e.g., Subject parts). `cert A` may
live outside Vault. Finally, import the cross-signed certificate into Vault
[using the `/issuers/import/cert` endpoint](/vault/api-docs/secret/pki#import-ca-certificates-and-keys).

If this process succeeded, and both `cert A` and `cert B` and their key
material lives in Vault, the newly imported cross-signed certificate
will have a `ca_chain` response field [during read](/vault/api-docs/secret/pki#read-issuer)
containing `cert A`, and `cert B`'s `ca_chain` will contain the cross-signed
cert and its `ca_chain` value.

~> Note: Regardless of issuer type, is important to provide all relevant
   parameters as they were originally; Vault does not infer e.g., the Subject
   name parameters from the existing issuer; it merely reuses the same key
   material.

##### Notes on `manual_chain`

If an intermediate is cross-signed and imported into the same mount as its
pair, Vault will not detect the cross-signed pairs during automatic chain
building. As a result, leaf issuance will have a chain that only includes
one of these pairs of chains. This is because the leaf issuance's `ca_chain`
parameter copies the value from signing issuer directly, rather than computing
its own copy of the chain.

To fix this, update the `manual_chain` field on the [issuers](/vault/api-docs/secret/pki#update-issuer)
to include the chains of both pairs. For instance, given `intA` signed by
`rootA` and `intB` signed by `rootB` as its cross-signed version, one
could do the following:

```
$ vault patch pki/issuer/intA manual_chain=self,rootA,intB,rootB
$ vault patch pki/issuer/intB manual_chain=self,rootB,intA,rootA
```

This will ensure that issuance with either copy of the intermediate reports
the full cross-signed chain when signing leaf certs.

### Reissuance primitive

The second most common type of rotation primitive. In this scheme, the existing
key material is used to generate a new certificate, usually at a much later
point in time from the existing issuance.

While similar to the cross-signed primitive, this one differs in that usually
the reissuance happens after the original certificate expires or is close to
expiration and is reissued by the original root CA. In the event of a
self-signed certificate (e.g., a root certificate), this parent certificate
would be itself. In both cases, this changes the contents of the certificate
(due to the new serial number) but allows all existing leaf signatures to
still validate.

Unlike the cross-signed primitive, this primitive type can be used on all
types of certificates (including leaves, intermediates, and roots).

#### Process flow

```
          -------------------
         | generate key pair | ---------------> ...
          -------------------                   ...
           |              |                     ...
 --------------           --------------        ...
| generate CSR |   <->   | generate CSR |       ...
 --------------           --------------        ...
         |                    |                 ...
 ------------------      ------------------     ...
| signed by issuer | -> | signed by issuer | -> ...
 ------------------      ------------------     ...
```

In this process flow, a single key pair is generated at some point in time
and stored. The CSR (with same requested fields) is generated from this
common key material and signed by the same issuer at multiple points in
time, preserving all critical fields (Subject, Issuer, &c). While there is
strictly no limit on the number of times a key can be reissued, at some point
safety would dictate the key material should be rotated instead of being
continually reissued.

#### Certificate hierarchy

```
                          ------
              -----------| root |-------------
             /            ------              \
             |                                |
 ---------------                           ---------------
| original cert | <- same key material -> | reissued cert |
 ---------------              |            ---------------
                              |
                      -------------------
                     | leaf certificates |
                      -------------------
```

Note that while this again results in two trust paths, depending on which
intermediate certificate is presented and is still valid, only a root need be
trusted. When a reissued certificate is a root certificate, the issuance link is
simply self-loop. But, in this case, note that both certificates are
(technically) valid issuers of each other. This means it should be possible to
provide a reissued root certificate in the TLS certificate chain and have it
chain back to an existing root certificate in a trust store.

This primitive type is thus an incrementing primitive; the life cycle of an
existing key is extended into the future by issuing a new certificate with the
same key material from the existing authority.

#### Execution in Vault

To create a reissued root certificate in Vault, use [`/issuers/generate/root/existing`
endpoint](/vault/api-docs/secret/pki#generate-root). This allows the generation of a new
root certificate with the existing key material (via the `key_ref` request parameter).
If this process succeeded, when [reading the issuer](/vault/api-docs/secret/pki#read-issuer)
(via `GET /issuer/:issuer_ref`), both issuers (old and reissued) will appear in
each others' `ca_chain` response field (unless prevented so by a `manual_chain`
value).

To create a reissued intermediate certificate in Vault, this is a three step
process:

 1. Use the [`/issuers/generate/intermediate/existing`
    endpoint](/vault/api-docs/secret/pki#generate-intermediate-csr)
    to generate a new CSR with the existing key material with the `key_ref`
    request parameter.
 2. Sign this CSR via the same signing process under the same issuer. This
    step is specific to the parent CA, which may or may not be Vault.
 3. Finally, use the [`/intermediate/set-signed` endpoint](/vault/api-docs/secret/pki#import-ca-certificates-and-keys)
    to import the signed certificate from step 2.

If the process to reissue an intermediate certificate succeeded, when
[reading the issuer](/vault/api-docs/secret/pki#read-issuer) (via
`GET /issuer/:issuer_ref`), both issuers (old and reissued) will have
the same `ca_chain` response field, except for the first entry (unless
prevented so by a `manual_chain` value).

~> Note: Regardless of issuer type, is important to provide all relevant
   parameters as they were originally; Vault does not infer e.g., the Subject
   name parameters from the existing issuer; it merely reuses the same key
   material.

### Temporal primitives

We can use the above primitive types to rotate roots and intermediates to new
keys and extend their lifetimes. This time-based rotation is what ultimately
allows us to rotate root certificates.

There's two main variants of this: a **forward** primitive, wherein an old
certificate is used to bless new key material, and a **backwards** primitive,
wherein a new certificate is used to bless old key material. Both of these
primitives are independently used by Let's Encrypt in the aforementioned
chain of trust document:

 - The link from DST Root CA X3 to ISRG Root X1 is an example of a forward
   primitive.
 - The link from ISRG Root X1 to R3 (which was originally signed by DST Root
   CA X3) is an example of a backwards primitive.

For most organizations with a hierarchical structured CA setup, cross-signing
all intermediates with both the new and old root CAs is sufficient for root
rotation.

However, for organizations which have directly issued leaf certificates from a
root, the old root will need to be reissued under the new root (with shorter
duration) to allow these certificates to continue to validate. This combines
both of the above primitives (cross-signing and reissuance) into a single
backwards primitive step. In the future, these organizations should probably
move to a more standard, hierarchical setup.

### Limitations of primitives

The certificate's [Authority Key Identifier](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.1)
extension field may contain either or both of the issuer's keyIdentifier
(a hash of the public key) or both the issuer's Subject and Serial Number
fields. Generating certificates with the latter enabled (luckily not possible
in Vault, especially so since Vault uses strictly random serial numbers)
prevents building a proper cross-signed chain without re-issuing the same
serial number, which will not work with most browsers' trust stores and
validation engines, due to [caching of
certificates](https://support.mozilla.org/en-US/kb/Certificate-contains-the-same-serial-number-as-another-certificate)
used in successful validations. In the strictest sense, when using a
cross-signing primitive (from a different CA), the intermediate could be reissued
with the same serial number, assuming no previous certificate was issued by that
CA with that serial. This does not work when using a reissuance primitive as these
are technically the same authority and thus this authority must issue
certificates with unique serial numbers.

## Suggested root rotation procedure

The following is a suggested process for achieving root rotation easily and
without (outage) impact to the broader organization, assuming [best
practices](/vault/docs/secrets/pki/considerations#use-a-ca-hierarchy) are
being followed. Some adaption will be necessary.

Note that this process takes time. How much time is dependent on the
automation level and operational awareness of the organization.

1. [Generate](/vault/api-docs/secret/pki#generate-root) the new root
   certificate. For clarity, it is suggested to use a new common name
   to distinguish it from the old root certificate. Key material need
   not be the same.

2. [Cross-sign](#cross-signed-primitive) all existing intermediates.
   It is important to update the manual chain on the issuers as discussed
   in that section, as we assume servers are configured to combine the
   `certificate` field with the `ca_chain` field on renewal and issuance,
   thus getting the cross-signed intermediates.

3. Encourage rotation to pickup the new cross-signed intermediates. With
   short-lived certificates, this should [happen
   automatically](/vault/docs/secrets/pki/considerations#automate-leaf-certificate-renewal).
   However, for some long-lived certs, it is suggested to rotate them
   manually and proactively. This step takes time, and depends on the
   types of certificates issued (e.g., server certs, code signing, or client
   auth).

4. Once _all_ chains have been updated, new systems can be brought online
   with only the new root certificate, and connect to all existing systems.

5. Existing systems can now be migrated with a one-shot root switch: the
   new root can be added and the old root can be removed at the same time.
   Assuming the above step 3 can be achieved in a reasonable amount of time,
   this decreases the time it takes to move the majority of systems over to
   fully using the new root and no longer trusting the old root. This step
   also takes time, depending on how quickly the organization can migrate
   roots and ensure all such systems are migrated. If some systems are
   offline and only infrequently online (or, if they have hard-coded
   certificate stores and need to reach obsolescence first), the organization
   might not be ready to move on to future steps.

6. At this point, since all systems now use the new root, it is safe to remove
   or archive the old root and intermediates, updating the manual chain to
   point strictly to the new intermediate+root.

At this point, rotation is fully completed.

## Tutorial

Refer to the [Build Your Own Certificate Authority (CA)](/vault/tutorials/secrets-management/pki-engine)
guide for a step-by-step tutorial.

Have a look at the [PKI Secrets Engine with Managed Keys](/vault/tutorials/enterprise/managed-key-pki)
for more about how to use externally managed keys with PKI.

## API

The PKI secrets engine has a full HTTP API. Please see the
[PKI secrets engine API](/vault/api-docs/secret/pki) for more
details.

layout  docs page title   PKI   Secrets Engine  Rotation Primitives  description  The PKI secrets engine for Vault generates TLS certificates         PKI secrets engine   rotation primitives  Since Vault 1 11 0  Vault s PKI Secrets Engine supports multiple issuers in a single mount point  By using the certificate types below  rotation can be accomplished in various situations involving both root and intermediate CAs managed by Vault      X 509 certificate fields  X 509 is a complex specification  modern implementations tend to refer to  RFC 5280  https   datatracker ietf org doc html rfc5280  for specific details  For validation of certificates  both RFC 5280 and the TLS validation  RFC 6125  https   datatracker ietf org doc html rfc6125  are important for understanding how to achieve rotation   The following is a simplification of these standards for the purpose of this document   Every X 509 certificate begins with an asymmetric key pair  using an algorithm like RSA or ECDSA  This key pair is used to create a Certificate Signing Request  CSR   which contains a set of fields the requester would like in the final certificate  but  it is up to the Certificate Authority  CA  to decide what fields to take from the CSR and which to override   The CSR also contains the public key of the pair  which is signed by the private key of the key pair to prove possession  Usually  the requester would ask for attributes in the Subject field of the CSR or in the Subject Alternative Name extension CSR to be respected in the final certificate  It is up to the CA if these values are trusted or not  When approved by the issuing authority  which may be backed by this asymmetric key itself in the case of a root self signed certificate   the authority attaches the Subject of  its  certificate to the issued certificate in the Issuer field  assigns a unique serial number to the issued certificate  and signs the set of fields with its private key  thus creating the certificate   There are some important restrictions here      One certificate can only have one Issuer  but this issuer is identified by    the Subject on the issuing certificate and its public key     One key pair can be used for multiple certificates  but one certificate can    only have one backing key material   The following fields on the final certificate are relevant to rotation      The backing  public  https   datatracker ietf org doc html rfc5280 section 4 1 2 7     and private key material  Subject Public Key Info        Note that the private key is not included in the certificate but is      uniquely determined by the public key material     The  Subject  https   datatracker ietf org doc html rfc5280 section 4 1 2 6  of the certificate       This identifies the entity to which the certificate was issued  While the      SAN values  in the  Subject Alternative Name  https   datatracker ietf org doc html rfc5280 section 4 2 1 6       extension  is useful when validating TLS Server certificates against the      negotiated hostname and URI  it isn t generally relevant for the purposes      of validating intermediate certificate chains or in rotation     The  Validity  https   datatracker ietf org doc html rfc5280 section 4 1 2 5     period of this certificate       Notably  RFC 5280 does not place any requirements around the issued      certificate s validity period relative to the validity period of the      issuing certificate  However  it  does state  https   datatracker ietf org doc html rfc5280 section 4 1 2 5       that certificates ought to be revoked if their status cannot be maintained      up to their notAfter date  This is why Vault 1 11 s   pki issuer  issuer ref       configuration endpoint maintains the  leaf not after behavior  per issuer      rather than per role       Additionally  some browsers will place ultimate trust in the certificates      in their trust stores  even when these certificates are expired         Note that this only applies to certificates in the trust store  validity        periods will still be enforced for certificates not in the store  such        as intermediates      The  Issuer  https   datatracker ietf org doc html rfc5280 section 4 1 2 4  and     signatureValue  https   datatracker ietf org doc html rfc5280 section 4 1 1 3     of this certificate       In the issued certificate s Issuer field  the issuing certificate places      its own Subject value  This allows the issuer to be identified later       without having to try signature validation against every known local      certificate   when validating the presented certificate and chain       The signature over the entire certificate  by the issuer s private key       is then placed in the signatureValue field     The optional  Authority Key Identifier  https   datatracker ietf org doc html rfc5280 section 4 2 1 1     field       This field can contain either  or both  of two values         The hash of the issuer s public key  This extension is set and this        value is filled in by Vault         The Issuer s Subject and Serial Number  This value is not set by Vault       The latter is a dangerous restriction for the purposes of rotation  it      prevents cross signing and reissuance as the new issuing certificates       while having the same backing key material  will have different serial      numbers  See the  Limitations of Primitives   limitations of primitives       section below for more information on this restriction     The  Serial Number  https   datatracker ietf org doc html rfc5280 section 4 1 2 2     of this certificate       This field is unique to a specific issuer  when a certificate is      reissued by its parent authority  it will always have a different serial      number field     The  CRL distribution  https   datatracker ietf org doc html rfc5280 section 4 2 1 13     point field       This is a field detailing where a CRL is expected to exist for this      certificate and under which CRL issuers  defaulting to the issuing      certificate itself  the CRL is expected to be signed by  This is mostly      informational and for server software like nginx  Vault s Cert Auth method       and Apache  CRLs are provided to the server  rather than having the      server fetch CRLs for certificates automatically       Note that root certificates  in browsers trust stores  are generally not      considered revocable  However  if an intermediate is revoked by serial       it will appear on its parent s CRL  and may prevent rotation from      happening      X 509 rotation primitives  Rotation  from an organizational standpoint  can only safely happen with certain intermediate X 509 certificates being issued  To distinguish the two types of certificates used to achieve rotation  this document notates them as  primitives    Rotation of an end entity certificate is trivial from an X 509 trust chain perspective  this process happens every day and should only depend on what is in the trust store and not the end entity certificate itself  In Vault  the requester would hit the various issuance endpoints    pki issue  name  or   pki sign  name     or use the unsafe   pki sign verbatim   and swap out the old certificate with the new certificate and reload the configuration or restart the service  Other parts of the organizations might use  ACME  https   datatracker ietf org doc html rfc8555  for certificate issuance and rotation  especially if the service is public facing  and thus needs to be issued by a Public CA   Given it was signed by a trusted root  any devices connecting to the service would not know the difference   Rotation of intermediate certificates is almost as easy  Assuming a decent operational setup  wherein during end entity issuance  the full certificate chain is updated in the service s configuration   this should be as easy as creating a new intermediate CA  signing it against the root CA  and then beginning issuance against the new intermediate certificate  In Vault  if the intermediate is generated in an existing mount path  or is moved into such   the requesting entity shouldn t care much  Under ACME  Let s Encrypt has successfully rotated intermediates to present a cross signed chain   for older Android devices  https   letsencrypt org 2020 12 21 extending android compatibility html    Assuming the old intermediate s parent s  are still valid and trusted  certificates issued under old intermediates should continue to validate   The hard part of rotation  calling for the use of these primitives  is rotating root certificates  These live in every device s trust store and are hard to update from an organization wide operational perspective  Unless the organization can swap out roots almost instantaneously and simultaneously  e g   via an agent  with no missed devices  this process will likely span months   To make this process lower risk  there are various primitive certificate types that use the  above certificate fields   x 509 certificate fields   Key to their success is the following note      Note  While certificates are added to the trust store  it is ultimately    the associated key material that determines trust  two issuer certificates    with the same subject but different public keys cannot validate the same    leaf certificate  only if the keys are the same can this occur       Cross Signed primitive  This is the most common type of rotation primitive  A common CSR is signed by two CAs  resulting in two certificates  These certificates must have the same Subject  but may have different Issuers and will have different Serial Numbers  and the same backing key material  to allow certificates they sign to be trusted by either variant   Note that  due to restrictions in how end entity certificates are used and validated  services and validation libraries expect only one   cross signing most typically only applies to intermediate        A note on Cross Signed roots  Technically  cross signing can occur between two roots  allowing trust bundles with either root to validate certs issued through the other  However  this process creates a certificate that is effectively an intermediate  as it is no longer self signed  and usually must be served alongside the trust chain  Given this restriction  it s preferable to instead cross sign the top level intermediates under the root unless strictly necessary when the old root certificate has been used to directly issue leaf certificates   So  the rest of this process flow assumes an intermediate is being cross signed as this is more common         Process flow                                           generate key pair                                                                                generate CSR          generate CSR                                                                                signed by           signed by                   root A              root B                                                                      Here  a key pair was generated at some point in time  Two CSRs are created and sent to two different root authorities  Root A and Root B   These result in two separate certificates  potentially with different validity periods  with the same Subject and same backing key material   Note that this cross signing need not happen simultaneously  there could be a gap of several years between the first and second certificate  Additionally  there s no limit on the number of cross signed  duplicate   used loosely  with the same subject and key material  certificates  this could be cross signed by many different root certificates if necessary and desired         Certificate hierarchy                                                                      root A                                              root B                                                                                intermediate C       same key material      intermediate D                                                                                leaf certificates                                                  The above process results in two trust paths  either of root A or root B  or both  could exist in the client s trust stores and the leaf certificate would validate correctly  Because the same key material is used for both intermediate certificates  C and D   the issued leaf certificate s signature field would be the same regardless of which intermediate was contacted   Cross signing is thus a unifying primitive  two separate trust paths now join into a single one  by having leaf certificate s issuer field to point to two separate paths  via duplication of the certificate in the chain  and would be conditionally validated based on which root is present in the trust store   This construct is documented and used in several places      https   letsencrypt org certificates     https   scotthelme co uk cross signing alternate trust paths how they work     https   security stackexchange com questions 14043 what is the use of cross signing certificates in x 509       Execution in Vault  To create a cross signed certificate in Vault  use the    intermediate cross sign  endpoint   vault api docs secret pki generate intermediate csr   Here  when creating a cross signature to all  cert B  to be validated by  cert A   provide the values   key ref   all Subject parts   c  for  cert B  during intermediate generation  Then sign this CSR  using the    issuer  issuer ref sign intermediate  endpoint   vault api docs secret pki sign intermediate   with  cert A  s reference and provide necessary values from  cert B   e g   Subject parts    cert A  may live outside Vault  Finally  import the cross signed certificate into Vault  using the   issuers import cert  endpoint   vault api docs secret pki import ca certificates and keys    If this process succeeded  and both  cert A  and  cert B  and their key material lives in Vault  the newly imported cross signed certificate will have a  ca chain  response field  during read   vault api docs secret pki read issuer  containing  cert A   and  cert B  s  ca chain  will contain the cross signed cert and its  ca chain  value      Note  Regardless of issuer type  is important to provide all relevant    parameters as they were originally  Vault does not infer e g   the Subject    name parameters from the existing issuer  it merely reuses the same key    material         Notes on  manual chain   If an intermediate is cross signed and imported into the same mount as its pair  Vault will not detect the cross signed pairs during automatic chain building  As a result  leaf issuance will have a chain that only includes one of these pairs of chains  This is because the leaf issuance s  ca chain  parameter copies the value from signing issuer directly  rather than computing its own copy of the chain   To fix this  update the  manual chain  field on the  issuers   vault api docs secret pki update issuer  to include the chains of both pairs  For instance  given  intA  signed by  rootA  and  intB  signed by  rootB  as its cross signed version  one could do the following         vault patch pki issuer intA manual chain self rootA intB rootB   vault patch pki issuer intB manual chain self rootB intA rootA      This will ensure that issuance with either copy of the intermediate reports the full cross signed chain when signing leaf certs       Reissuance primitive  The second most common type of rotation primitive  In this scheme  the existing key material is used to generate a new certificate  usually at a much later point in time from the existing issuance   While similar to the cross signed primitive  this one differs in that usually the reissuance happens after the original certificate expires or is close to expiration and is reissued by the original root CA  In the event of a self signed certificate  e g   a root certificate   this parent certificate would be itself  In both cases  this changes the contents of the certificate  due to the new serial number  but allows all existing leaf signatures to still validate   Unlike the cross signed primitive  this primitive type can be used on all types of certificates  including leaves  intermediates  and roots         Process flow                                               generate key pair                                                                                generate CSR             generate CSR                                                                                signed by issuer        signed by issuer                                                                   In this process flow  a single key pair is generated at some point in time and stored  The CSR  with same requested fields  is generated from this common key material and signed by the same issuer at multiple points in time  preserving all critical fields  Subject  Issuer   c   While there is strictly no limit on the number of times a key can be reissued  at some point safety would dictate the key material should be rotated instead of being continually reissued        Certificate hierarchy                                                                  root                                                                                original cert      same key material      reissued cert                                                                                leaf certificates                                                  Note that while this again results in two trust paths  depending on which intermediate certificate is presented and is still valid  only a root need be trusted  When a reissued certificate is a root certificate  the issuance link is simply self loop  But  in this case  note that both certificates are  technically  valid issuers of each other  This means it should be possible to provide a reissued root certificate in the TLS certificate chain and have it chain back to an existing root certificate in a trust store   This primitive type is thus an incrementing primitive  the life cycle of an existing key is extended into the future by issuing a new certificate with the same key material from the existing authority        Execution in Vault  To create a reissued root certificate in Vault  use    issuers generate root existing  endpoint   vault api docs secret pki generate root   This allows the generation of a new root certificate with the existing key material  via the  key ref  request parameter   If this process succeeded  when  reading the issuer   vault api docs secret pki read issuer   via  GET  issuer  issuer ref    both issuers  old and reissued  will appear in each others   ca chain  response field  unless prevented so by a  manual chain  value    To create a reissued intermediate certificate in Vault  this is a three step process    1  Use the    issuers generate intermediate existing      endpoint   vault api docs secret pki generate intermediate csr      to generate a new CSR with the existing key material with the  key ref      request parameter   2  Sign this CSR via the same signing process under the same issuer  This     step is specific to the parent CA  which may or may not be Vault   3  Finally  use the    intermediate set signed  endpoint   vault api docs secret pki import ca certificates and keys      to import the signed certificate from step 2   If the process to reissue an intermediate certificate succeeded  when  reading the issuer   vault api docs secret pki read issuer   via  GET  issuer  issuer ref    both issuers  old and reissued  will have the same  ca chain  response field  except for the first entry  unless prevented so by a  manual chain  value       Note  Regardless of issuer type  is important to provide all relevant    parameters as they were originally  Vault does not infer e g   the Subject    name parameters from the existing issuer  it merely reuses the same key    material       Temporal primitives  We can use the above primitive types to rotate roots and intermediates to new keys and extend their lifetimes  This time based rotation is what ultimately allows us to rotate root certificates   There s two main variants of this  a   forward   primitive  wherein an old certificate is used to bless new key material  and a   backwards   primitive  wherein a new certificate is used to bless old key material  Both of these primitives are independently used by Let s Encrypt in the aforementioned chain of trust document      The link from DST Root CA X3 to ISRG Root X1 is an example of a forward    primitive     The link from ISRG Root X1 to R3  which was originally signed by DST Root    CA X3  is an example of a backwards primitive   For most organizations with a hierarchical structured CA setup  cross signing all intermediates with both the new and old root CAs is sufficient for root rotation   However  for organizations which have directly issued leaf certificates from a root  the old root will need to be reissued under the new root  with shorter duration  to allow these certificates to continue to validate  This combines both of the above primitives  cross signing and reissuance  into a single backwards primitive step  In the future  these organizations should probably move to a more standard  hierarchical setup       Limitations of primitives  The certificate s  Authority Key Identifier  https   datatracker ietf org doc html rfc5280 section 4 2 1 1  extension field may contain either or both of the issuer s keyIdentifier  a hash of the public key  or both the issuer s Subject and Serial Number fields  Generating certificates with the latter enabled  luckily not possible in Vault  especially so since Vault uses strictly random serial numbers  prevents building a proper cross signed chain without re issuing the same serial number  which will not work with most browsers  trust stores and validation engines  due to  caching of certificates  https   support mozilla org en US kb Certificate contains the same serial number as another certificate  used in successful validations  In the strictest sense  when using a cross signing primitive  from a different CA   the intermediate could be reissued with the same serial number  assuming no previous certificate was issued by that CA with that serial  This does not work when using a reissuance primitive as these are technically the same authority and thus this authority must issue certificates with unique serial numbers      Suggested root rotation procedure  The following is a suggested process for achieving root rotation easily and without  outage  impact to the broader organization  assuming  best practices   vault docs secrets pki considerations use a ca hierarchy  are being followed  Some adaption will be necessary   Note that this process takes time  How much time is dependent on the automation level and operational awareness of the organization   1   Generate   vault api docs secret pki generate root  the new root    certificate  For clarity  it is suggested to use a new common name    to distinguish it from the old root certificate  Key material need    not be the same   2   Cross sign   cross signed primitive  all existing intermediates     It is important to update the manual chain on the issuers as discussed    in that section  as we assume servers are configured to combine the     certificate  field with the  ca chain  field on renewal and issuance     thus getting the cross signed intermediates   3  Encourage rotation to pickup the new cross signed intermediates  With    short lived certificates  this should  happen    automatically   vault docs secrets pki considerations automate leaf certificate renewal      However  for some long lived certs  it is suggested to rotate them    manually and proactively  This step takes time  and depends on the    types of certificates issued  e g   server certs  code signing  or client    auth    4  Once  all  chains have been updated  new systems can be brought online    with only the new root certificate  and connect to all existing systems   5  Existing systems can now be migrated with a one shot root switch  the    new root can be added and the old root can be removed at the same time     Assuming the above step 3 can be achieved in a reasonable amount of time     this decreases the time it takes to move the majority of systems over to    fully using the new root and no longer trusting the old root  This step    also takes time  depending on how quickly the organization can migrate    roots and ensure all such systems are migrated  If some systems are    offline and only infrequently online  or  if they have hard coded    certificate stores and need to reach obsolescence first   the organization    might not be ready to move on to future steps   6  At this point  since all systems now use the new root  it is safe to remove    or archive the old root and intermediates  updating the manual chain to    point strictly to the new intermediate root   At this point  rotation is fully completed      Tutorial  Refer to the  Build Your Own Certificate Authority  CA    vault tutorials secrets management pki engine  guide for a step by step tutorial   Have a look at the  PKI Secrets Engine with Managed Keys   vault tutorials enterprise managed key pki  for more about how to use externally managed keys with PKI      API  The PKI secrets engine has a full HTTP API  Please see the  PKI secrets engine API   vault api docs secret pki  for more details


vault page title Enrollment over Secure Transport EST within Vault PKI Secrets Engines This document covers configuration and limitations of Vault s PKI Secrets Engine An overview of the Enrollment over Secure Transport protocol implementation within Vault implementation of the EST protocol https datatracker ietf org doc html rfc7030 EnterpriseAlert inline true layout docs PKI secrets engine Enrollment over Secure Transport EST EnterpriseAlert inline true

Answer:
---
layout: docs
page_title: Enrollment over Secure Transport (EST) within Vault | PKI - Secrets Engines
description: An overview of the Enrollment over Secure Transport protocol implementation within Vault.
---

# PKI secrets engine - Enrollment over Secure Transport (EST) <EnterpriseAlert inline="true" />

This document covers configuration and limitations of Vault's PKI Secrets Engine
implementation of the [EST protocol](https://datatracker.ietf.org/doc/html/rfc7030) <EnterpriseAlert inline="true" />.

## What is Enrollment over Secure Transport (EST)?

The EST protocol is an IETF standardized protocol, [RFC 7030](https://datatracker.ietf.org/doc/html/rfc7030),
that allows clients to acquire client certificates and associated
Certificate Authority (CA) certificates.

## Enabling EST support on a Vault PKI mount

The following is a list of steps required to configure an existing PKI
mount to serve EST clients. Each of which can be broken down within three main
categories.

 1. [Authentication mechanisms](#configuring-est-authentication)
 1. [Updating PKI tunable parameters](#updating-the-pki-mount-tunable-parameters)
 1. [PKI EST configuration](#pki-est-configuration)

### Configuring EST Authentication

The EST protocol specifies a few different authentication mechanisms, of which
Vault supports two.

 1. [HTTP-Based Client authentication](/vault/docs/auth/userpass)
 1. [Certificate TLS authentication](/vault/docs/auth/cert)

Both of these authentication mechanisms leverage a separate Vault authentication
mount, within the same namespace, to validate the client provided credentials
along with the client's ACL policy to enforce. While both authentication
schemes can be enabled at once, only a single mount will be used to authenticate
a client based on the way credentials were provided through EST. If an EST client sends
HTTP-Based authentication credentials, they will be preferred over TLS client
certificates.

For proper accounting, mounts supporting EST authentication should be
dedicated to this purpose, not shared with other workflows.  In other words,
create a new auth mount for EST even if you already have one of the same
type for other purposes.

When setting up the authentication mount for EST clients, the token type must
be configured to return [batch tokens](/vault/docs/concepts/tokens#batch-tokens).
Batch tokens are required to avoid an excessive amount of leases being generated
and persisted as every EST incoming request needs to be authenticated.

The path within an ACL policy, must match the internal redirected path including
the mount and not the `.well-known/est/` URI the client is initially using.
The path to use within the plugin depends on the path policy that is in configured
for the EST label being used by the client.

If using the `sign-verbatim` as a path policy, the following
ACL policy will allow an authenticated client access the required PKI EST paths.
```
path “pki/est/simpleenroll” {
  capabilities=[“update”, “create”]
}
path “pki/est/simplereenroll” {
  capabilities=[“update”, “create”]
}
```

For a role base path policy, this sample policy can be used
```
path “pki/roles/my-role-name/est/simpleenroll” {
  capabilities=[“update”, “create”]
}
path “pki/roles/my-role-name/est/simplereenroll” {
  capabilities=[“update”, “create”]
}
```

#### Updating the PKI mount tunable parameters

Once the authentication mount has been created and configured, the authentication mount's accessor
will need to be captured and added within the PKI mount's [delegated auth accessors](/vault/api-docs/system/mounts#delegated_auth_accessors).

To get an authentication mount's accessor field, the following command can be used.

```shell-session
$ vault read -field=accessor sys/auth/auth/userpass
```

For EST to work within certain clients, a few response headers need to be explicitly allowed
along with configuring the list of accessors the mount can delegate authentication towards.
The following will grant the required response headers, you will need to replace the values for the `delegated-auth-accessors`
to match your values.

```shell-session
$ vault secrets tune \
  -allowed-response-headers="Content-Transfer-Encoding" \
  -allowed-response-headers="Content-Length" \
  -allowed-response-headers="WWW-Authenticate" \
  -delegated-auth-accessors="auth_userpass_e2f4f6d5" \
  -delegated-auth-accessors="auth_cert_4088ac2d" \
  pki
```

#### PKI EST configuration

The EST protocol specifies that an EST server must support a URI path-prefix of
`.well-known/est/` as defined in [RFC-5785](https://datatracker.ietf.org/doc/html/rfc5785).
EST client's normally don't provide any sort of configuration for different path-prefixes, and will
default to hitting the host on the path `https://<hostname>:<port>/.well-known/est/`.

Some clients allow a single label, sometimes referred to as `additional path segment`,
to accommodate different issuers. This label will be added to the path after
the est path such as `https://<hostname>:<port>/.well-known/est/<label>/`.

To provide different restrictions around usage (defaults, an issuer or role),
for EST protocol endpoints, a path policy is associated with the EST
label.

@include 'pki-est-default-policy.mdx'

Within the Vault [EST configuration API](/vault/api-docs/secret/pki/issuance#set-est-configuration), a PKI
mount can be specified as the default mount by enabling [default_mount](/vault/api-docs/secret/pki/issuance#default_mount)
to true, or provide a mapping of a label within [label_to_path_policy](/vault/api-docs/secret/pki/issuance#label_to_path_policy)

As an example of a complete EST configuration, that would enable the pki mount
to register the .well-known/est default label, along with two additional labels
of test-label and sign-all.

The test-label would use the existing est-clients PKI role for restrictions and defaults,
leveraging the issuer specified within the role. The other two labels, default and sign-all will
leverage a sign-verbatim type role, allowing any identifier to be issued using the default
issuer.

```shell-session
vault write pki/config/est -<<EOC
{
  "enabled": true,
  "default_mount": true,
  "default_path_policy": "sign-verbatim",
  "label_to_path_policy": {
    "test-label": "role:est-clients",
    "sign-all": "sign-verbatim"
  },
  "authenticators": {
    "cert": {
      "accessor": "auth_cert_4088ac2d"
    },
    "userpass": {
      "accessor": "auth_userpass_e2f4f6d5"
    }
  }
}
EOC
```

## Limitations

### EST API Support

The initial implementation covers solely the required API endpoints of the EST protocol.
The following optional features from the specification are not currently supported.

 - [Full CMC](https://datatracker.ietf.org/doc/html/rfc7030#section-4.3)
 - [Server-side key generation](https://datatracker.ietf.org/doc/html/rfc7030#section-4.4)
 - [CSR attribute endpoints](https://datatracker.ietf.org/doc/html/rfc7030#section-4.5)

### Well Known redirections

The EST configuration parameters `default_mount` and/or `label_to_path_policy` can be used to register
paths within the .well-known path space. The following limitations apply:

 - Only a single PKI mount, across all namespaces, can be enabled as the `default_mount`.
 - Labels within `label_to_path_policy` must also be unique across all PKI mounts regardless of namespace.
 - Care must be taken if enabling EST on a [local](/vault/docs/commands/secrets/enable#local) PKI mount on
   performance secondary clusters. Vault cannot guarantee the configured EST labels do
   not conflict across different PKI mounts in this use-case. This can lead to
   different issuers being used across clusters for the same EST labels.

## API

The PKI secrets engine has a full HTTP API. Please see the
[PKI secrets engine API](/vault/api-docs/secret/pki) for more details.

layout  docs page title  Enrollment over Secure Transport  EST  within Vault   PKI   Secrets Engines description  An overview of the Enrollment over Secure Transport protocol implementation within Vault         PKI secrets engine   Enrollment over Secure Transport  EST   EnterpriseAlert inline  true      This document covers configuration and limitations of Vault s PKI Secrets Engine implementation of the  EST protocol  https   datatracker ietf org doc html rfc7030   EnterpriseAlert inline  true          What is Enrollment over Secure Transport  EST    The EST protocol is an IETF standardized protocol   RFC 7030  https   datatracker ietf org doc html rfc7030   that allows clients to acquire client certificates and associated Certificate Authority  CA  certificates      Enabling EST support on a Vault PKI mount  The following is a list of steps required to configure an existing PKI mount to serve EST clients  Each of which can be broken down within three main categories    1   Authentication mechanisms   configuring est authentication   1   Updating PKI tunable parameters   updating the pki mount tunable parameters   1   PKI EST configuration   pki est configuration       Configuring EST Authentication  The EST protocol specifies a few different authentication mechanisms  of which Vault supports two    1   HTTP Based Client authentication   vault docs auth userpass   1   Certificate TLS authentication   vault docs auth cert   Both of these authentication mechanisms leverage a separate Vault authentication mount  within the same namespace  to validate the client provided credentials along with the client s ACL policy to enforce  While both authentication schemes can be enabled at once  only a single mount will be used to authenticate a client based on the way credentials were provided through EST  If an EST client sends HTTP Based authentication credentials  they will be preferred over TLS client certificates   For proper accounting  mounts supporting EST authentication should be dedicated to this purpose  not shared with other workflows   In other words  create a new auth mount for EST even if you already have one of the same type for other purposes   When setting up the authentication mount for EST clients  the token type must be configured to return  batch tokens   vault docs concepts tokens batch tokens   Batch tokens are required to avoid an excessive amount of leases being generated and persisted as every EST incoming request needs to be authenticated   The path within an ACL policy  must match the internal redirected path including the mount and not the   well known est   URI the client is initially using  The path to use within the plugin depends on the path policy that is in configured for the EST label being used by the client   If using the  sign verbatim  as a path policy  the following ACL policy will allow an authenticated client access the required PKI EST paths      path  pki est simpleenroll      capabilities   update    create     path  pki est simplereenroll      capabilities   update    create          For a role base path policy  this sample policy can be used     path  pki roles my role name est simpleenroll      capabilities   update    create     path  pki roles my role name est simplereenroll      capabilities   update    create               Updating the PKI mount tunable parameters  Once the authentication mount has been created and configured  the authentication mount s accessor will need to be captured and added within the PKI mount s  delegated auth accessors   vault api docs system mounts delegated auth accessors    To get an authentication mount s accessor field  the following command can be used      shell session   vault read  field accessor sys auth auth userpass      For EST to work within certain clients  a few response headers need to be explicitly allowed along with configuring the list of accessors the mount can delegate authentication towards  The following will grant the required response headers  you will need to replace the values for the  delegated auth accessors  to match your values      shell session   vault secrets tune      allowed response headers  Content Transfer Encoding       allowed response headers  Content Length       allowed response headers  WWW Authenticate       delegated auth accessors  auth userpass e2f4f6d5       delegated auth accessors  auth cert 4088ac2d      pki           PKI EST configuration  The EST protocol specifies that an EST server must support a URI path prefix of   well known est   as defined in  RFC 5785  https   datatracker ietf org doc html rfc5785   EST client s normally don t provide any sort of configuration for different path prefixes  and will default to hitting the host on the path  https    hostname   port   well known est     Some clients allow a single label  sometimes referred to as  additional path segment   to accommodate different issuers  This label will be added to the path after the est path such as  https    hostname   port   well known est  label      To provide different restrictions around usage  defaults  an issuer or role   for EST protocol endpoints  a path policy is associated with the EST label    include  pki est default policy mdx   Within the Vault  EST configuration API   vault api docs secret pki issuance set est configuration   a PKI mount can be specified as the default mount by enabling  default mount   vault api docs secret pki issuance default mount  to true  or provide a mapping of a label within  label to path policy   vault api docs secret pki issuance label to path policy   As an example of a complete EST configuration  that would enable the pki mount to register the  well known est default label  along with two additional labels of test label and sign all   The test label would use the existing est clients PKI role for restrictions and defaults  leveraging the issuer specified within the role  The other two labels  default and sign all will leverage a sign verbatim type role  allowing any identifier to be issued using the default issuer      shell session vault write pki config est    EOC      enabled   true     default mount   true     default path policy    sign verbatim      label to path policy          test label    role est clients        sign all    sign verbatim          authenticators          cert            accessor    auth cert 4088ac2d              userpass            accessor    auth userpass e2f4f6d5              EOC         Limitations      EST API Support  The initial implementation covers solely the required API endpoints of the EST protocol  The following optional features from the specification are not currently supported       Full CMC  https   datatracker ietf org doc html rfc7030 section 4 3      Server side key generation  https   datatracker ietf org doc html rfc7030 section 4 4      CSR attribute endpoints  https   datatracker ietf org doc html rfc7030 section 4 5       Well Known redirections  The EST configuration parameters  default mount  and or  label to path policy  can be used to register paths within the  well known path space  The following limitations apply      Only a single PKI mount  across all namespaces  can be enabled as the  default mount      Labels within  label to path policy  must also be unique across all PKI mounts regardless of namespace     Care must be taken if enabling EST on a  local   vault docs commands secrets enable local  PKI mount on    performance secondary clusters  Vault cannot guarantee the configured EST labels do    not conflict across different PKI mounts in this use case  This can lead to    different issuers being used across clusters for the same EST labels      API  The PKI secrets engine has a full HTTP API  Please see the  PKI secrets engine API   vault api docs secret pki  for more details


vault Troubleshoot PKI Secrets Engine and ACME Secrets Engine s ACME server Solve common problems related to ACME client integration with Vault PKI page title PKI Secrets Engine Troubleshooting ACME layout docs Troubleshoot problems with ACME clients and Vault PKI Secrets Engine s ACME server

Answer:
---
layout: docs
page_title: 'PKI - Secrets Engine: Troubleshooting ACME'
description: Troubleshoot problems with ACME clients and Vault PKI Secrets Engine's ACME server.
---

# Troubleshoot PKI Secrets Engine and ACME

Solve common problems related to ACME client integration with Vault PKI
Secrets Engine's ACME server.

## Error: ACME feature requires local cluster 'path' field configuration to be set

If ACME works on some nodes of a Vault Enterprise cluster but not on
others, it likely means that the cluster address has not been set.

### Symptoms

When a Vault client reads the ACME config (`/config/acme`) on a
Performance Secondary nodes or when an ACME client attempts to connect to a
directory on this node, it will error with:

> ACME feature requires local cluster 'path' field configuration to be set

### Cause

In most cases, cluster path errors mean that the required cluster address is
not set in your cluster configuration parameter.

### Resolution

For each Performance Replication cluster, read the value of `/config/cluster`
and ensure the `path` field is set. When it is missing, update the URL to
point to this mount's path on a TLS-enabled address for this PR cluster; this
domain may be a load balanced or a DNS round robin address. For example:

```
$ vault write pki/config/cluster path=https://cluster-b.vault.example.com/v1/pki
```

Once this is done, re-read the ACME configuration and make sure no warnings
appear:

```
$ vault read pki/config/acme
```

## Error: Unable to register an account with the ACME server

### Symptoms

When registering a new account without an [External Account Binding
(EAB)](/vault/api-docs/secret/pki#acme-external-account-bindings), the
Vault Server rejects the request with a response like:

> Unable to register an account with ACME server

with further information provided in the debug logs (in the case of
`certbot`):

> Server requires external account binding.

or, if the client incorrectly contacted the server, an error like:

> The request must include a value for the 'externalAccountBinding' field

In either case, a new account needs to be created with an EAB token created
by Vault.

### Cause

If a server has been updated to require `eab_policy=always-required` in the
[ACME configuration](/vault/api-docs/secret/pki#set-acme-configuration),
new account registration (and reuse of existing accounts will fail).

### Resolution

Using a Vault token, [fetch a new external account
binding](/vault/api-docs/secret/pki#get-acme-eab-binding-token) for
the [desired directory](/vault/api-docs/v1.14.x/secret/pki#acme-directories):

```
$ vault write -f pki/roles/my-role-name/acme/new-eab
...
directory roles/my-role-name/acme/directory
id        bc8088d9-3816-5177-ae8e-d8393265f7dd
key       MHcCAQE... additional data elided ...
...
```

Then pass this new EAB token into the ACME client. For example, with
`certbot`:

```
$ certbot [... additional parameters ...] \
    --server https://cluster-b.vault.example.com/v1/pki/roles/my-role-name/acme/directory \
    --eab-kid bc8088d9-3816-5177-ae8e-d8393265f7dd \
    --eab-hmac-key MHcCAQE... additional data elided ...
```

Ensure that the ACME directory passed to the ACME client matches that
fetched from the Vault.

## Error: Failed to verify eab

### Symptoms

When initializing a new account against this Vault server, the ACME client
might error with a message like:

> The client lacks sufficient authorization :: failed to verify eab

This is caused by requesting an EAB from a directory not matching the
one the client used.

### Cause

If an EAB account token is incorrectly used with the wrong directory, the
ACME server will reject the request with an error about insufficient
permissions.

### Resolution

Ensure the requested EAB token matches the directory. For a given directory
at `/some/path/acme/directory`, fetch EAB tokens from
`/some/path/acme/new-eab`. The remaining resolution steps are the same as
for [debugging account registration
failures](#debugging-account-registration-failures).

## Error: ACME validation failed for `{challenge_id}`

### Symptoms

When viewing the Vault server logs or attempting to fetch a certificate via
an ACME client, an error like:

> ACME validation failed for a465a798-4400-6c17-6735-e1b38c23de38-tls-alpn-01: ...

indicates that the server was unable to validate this challenge accepted
by the client.

### Cause

Vault can not verify the server's identity through the client's requested
[challenge type](/vault/api-docs/secret/pki#acme-challenge-types) (`dns-01`,
`http-01`, or `tls-alpn-01`). Vault will not issue the certificate requested
by the client.

### Resolution

Ensure that DNS is configured correctly from the Vault server's perspective,
including setting [any custom DNS resolver](/vault/api-docs/secret/pki#dns_resolver).

Ensure that any firewalls are set up to allow Vault to talk to the relevant
systems (the DNS server in the case of `dns-01`, port 80 on the target
machine for `http-01`, or port 443 on the target machine for `tls-alpn-01`
challenges).

## Error: The client lacks sufficient authorization: account in status: revoked

### Symptoms

When attempting to renew a certificate, the ACME client reports an error:

> The client lacks sufficient authorization: account in status: revoked

### Cause

If you run a [manual tidy](/vault/api-docs/secret/pki#tidy_acme) or have
[auto-tidy](/vault/api-docs/secret/pki#configure-automatic-tidy) enabled
with `tidy_acme=true, Vault will periodically remove stale ACME accounts.

Connections from clients using removed accounts will be rejected.

### Resolution

Refer to the ACME client's documentation for removing cached local
configuration and setup a new account, specifying any EABs as required.

## Get help

Please provide the following information when contacting Hashicorp Support
or filing a GitHub issue to help with our investigation and reproducibility:

 - ACME client name and version
 - ACME client logs and/or output
 - Vault server **DEBUG** level logs

## Tutorial

Refer to the [Build Your Own Certificate Authority (CA)](/vault/tutorials/secrets-management/pki-engine)
guide for a step-by-step tutorial.

Have a look at the [PKI Secrets Engine with Managed Keys](/vault/tutorials/enterprise/managed-key-pki)
for more about how to use externally managed keys with PKI.

## API

The PKI secrets engine has a full HTTP API. Please see the
[PKI secrets engine API](/vault/api-docs/secret/pki) for more
details.

layout  docs page title   PKI   Secrets Engine  Troubleshooting ACME  description  Troubleshoot problems with ACME clients and Vault PKI Secrets Engine s ACME server         Troubleshoot PKI Secrets Engine and ACME  Solve common problems related to ACME client integration with Vault PKI Secrets Engine s ACME server      Error  ACME feature requires local cluster  path  field configuration to be set  If ACME works on some nodes of a Vault Enterprise cluster but not on others  it likely means that the cluster address has not been set       Symptoms  When a Vault client reads the ACME config    config acme   on a Performance Secondary nodes or when an ACME client attempts to connect to a directory on this node  it will error with     ACME feature requires local cluster  path  field configuration to be set      Cause  In most cases  cluster path errors mean that the required cluster address is not set in your cluster configuration parameter       Resolution  For each Performance Replication cluster  read the value of   config cluster  and ensure the  path  field is set  When it is missing  update the URL to point to this mount s path on a TLS enabled address for this PR cluster  this domain may be a load balanced or a DNS round robin address  For example         vault write pki config cluster path https   cluster b vault example com v1 pki      Once this is done  re read the ACME configuration and make sure no warnings appear         vault read pki config acme         Error  Unable to register an account with the ACME server      Symptoms  When registering a new account without an  External Account Binding  EAB    vault api docs secret pki acme external account bindings   the Vault Server rejects the request with a response like     Unable to register an account with ACME server  with further information provided in the debug logs  in the case of  certbot       Server requires external account binding   or  if the client incorrectly contacted the server  an error like     The request must include a value for the  externalAccountBinding  field  In either case  a new account needs to be created with an EAB token created by Vault       Cause  If a server has been updated to require  eab policy always required  in the  ACME configuration   vault api docs secret pki set acme configuration   new account registration  and reuse of existing accounts will fail        Resolution  Using a Vault token   fetch a new external account binding   vault api docs secret pki get acme eab binding token  for the  desired directory   vault api docs v1 14 x secret pki acme directories          vault write  f pki roles my role name acme new eab     directory roles my role name acme directory id        bc8088d9 3816 5177 ae8e d8393265f7dd key       MHcCAQE    additional data elided              Then pass this new EAB token into the ACME client  For example  with  certbot          certbot      additional parameters              server https   cluster b vault example com v1 pki roles my role name acme directory         eab kid bc8088d9 3816 5177 ae8e d8393265f7dd         eab hmac key MHcCAQE    additional data elided          Ensure that the ACME directory passed to the ACME client matches that fetched from the Vault      Error  Failed to verify eab      Symptoms  When initializing a new account against this Vault server  the ACME client might error with a message like     The client lacks sufficient authorization    failed to verify eab  This is caused by requesting an EAB from a directory not matching the one the client used       Cause  If an EAB account token is incorrectly used with the wrong directory  the ACME server will reject the request with an error about insufficient permissions       Resolution  Ensure the requested EAB token matches the directory  For a given directory at   some path acme directory   fetch EAB tokens from   some path acme new eab   The remaining resolution steps are the same as for  debugging account registration failures   debugging account registration failures       Error  ACME validation failed for   challenge id        Symptoms  When viewing the Vault server logs or attempting to fetch a certificate via an ACME client  an error like     ACME validation failed for a465a798 4400 6c17 6735 e1b38c23de38 tls alpn 01       indicates that the server was unable to validate this challenge accepted by the client       Cause  Vault can not verify the server s identity through the client s requested  challenge type   vault api docs secret pki acme challenge types    dns 01    http 01   or  tls alpn 01    Vault will not issue the certificate requested by the client       Resolution  Ensure that DNS is configured correctly from the Vault server s perspective  including setting  any custom DNS resolver   vault api docs secret pki dns resolver    Ensure that any firewalls are set up to allow Vault to talk to the relevant systems  the DNS server in the case of  dns 01   port 80 on the target machine for  http 01   or port 443 on the target machine for  tls alpn 01  challenges       Error  The client lacks sufficient authorization  account in status  revoked      Symptoms  When attempting to renew a certificate  the ACME client reports an error     The client lacks sufficient authorization  account in status  revoked      Cause  If you run a  manual tidy   vault api docs secret pki tidy acme  or have  auto tidy   vault api docs secret pki configure automatic tidy  enabled with  tidy acme true  Vault will periodically remove stale ACME accounts   Connections from clients using removed accounts will be rejected       Resolution  Refer to the ACME client s documentation for removing cached local configuration and setup a new account  specifying any EABs as required      Get help  Please provide the following information when contacting Hashicorp Support or filing a GitHub issue to help with our investigation and reproducibility      ACME client name and version    ACME client logs and or output    Vault server   DEBUG   level logs     Tutorial  Refer to the  Build Your Own Certificate Authority  CA    vault tutorials secrets management pki engine  guide for a step by step tutorial   Have a look at the  PKI Secrets Engine with Managed Keys   vault tutorials enterprise managed key pki  for more about how to use externally managed keys with PKI      API  The PKI secrets engine has a full HTTP API  Please see the  PKI secrets engine API   vault api docs secret pki  for more details


vault The PKI secrets engine for Vault generates TLS certificates Secrets Engine layout docs PKI secrets engine setup and usage This document provides a brief overview of the setup and usage of the PKI page title PKI Secrets Engines Setup and Usage

layout  docs page title   PKI   Secrets Engines  Setup and Usage  description  The PKI secrets engine for Vault generates TLS certificates         PKI secrets engine   setup and usage  This document provides a brief overview of the setup and usage of the PKI Secrets Engine      Setup  Most secrets engines must be configured in advance before they can perform their functions  These steps are usually completed by an operator or configuration management tool   1  Enable the PKI secrets engine         text      vault secrets enable pki    Success  Enabled the pki secrets engine at  pki             By default  the secrets engine will mount at the name of the engine  To    enable the secrets engine at a different path  use the   path  argument   1  Increase the TTL by tuning the secrets engine  The default value of 30 days may be too short  so increase it to 1 year         text      vault secrets tune  max lease ttl 8760h pki    Success  Tuned the secrets engine at  pki             Note that individual roles can restrict this value to be shorter on a    per certificate basis  This just configures the global maximum for this    secrets engine   1  Configure a CA certificate and private key  Vault can accept an existing key    pair  or it can generate its own self signed root  In general  we recommend    maintaining your root CA outside of Vault and providing Vault a signed    intermediate CA         text      vault write pki root generate internal          common name my website com          ttl 8760h     Key              Value                              certificate           BEGIN CERTIFICATE            expiration       1536807433    issuing ca            BEGIN CERTIFICATE            serial number    7c f1 fb 2c 6e 4d 99 0e 82 1b 08 0a 81 ed 61 3e 1d fa f5 29            The returned certificate is purely informative  The private key is safely    stored internally in Vault   1  Update the CRL location and issuing certificates  These values can be updated    in the future         text      vault write pki config urls          issuing certificates  http   127 0 0 1 8200 v1 pki ca           crl distribution points  http   127 0 0 1 8200 v1 pki crl     Success  Data written to  pki config urls         1  Configure a role that maps a name in Vault to a procedure for generating a    certificate  When users or machines generate credentials  they are generated    against this role         text      vault write pki roles example dot com          allowed domains my website com          allow subdomains true          max ttl 72h    Success  Data written to  pki roles example dot com            Usage  After the secrets engine is configured and a user machine has a Vault token with the proper permission  it can generate credentials   1   Generate a new credential by writing to the   issue  endpoint with the name     of the role          text       vault write pki issue example dot com           common name www my website com      Key                 Value                                   certificate              BEGIN CERTIFICATE             issuing ca               BEGIN CERTIFICATE             private key              BEGIN RSA PRIVATE KEY             private key type    rsa     serial number       1d 2e c6 06 45 18 60 0e 23 d6 c5 17 43 c0 fe 46 ed d1 50 be              The output will include a dynamically generated private key and certificate     which corresponds to the given role and expires in 72h  as dictated by our     role definition   The issuing CA and trust chain is also returned for     automation simplicity      Tutorial  Refer to the  Build Your Own Certificate Authority  CA    vault tutorials secrets management pki engine  guide for a step by step tutorial   Have a look at the  PKI Secrets Engine with Managed Keys   vault tutorials enterprise managed key pki  for more about how to use externally managed keys with PKI      API  The PKI secrets engine has a full HTTP API  Please see the  PKI secrets engine API   vault api docs secret pki  for more details