Build your own certificate authority (CA)

41min
Vault
Video
Interactive

Vault's PKI secrets engine can dynamically generate X.509 certificates on demand. This allows services to request certificates without going through the usual manual process of generating a private key and Certificate Signing Request (CSR), submitting to a Certificate Authority (CA), and then waiting for the verification and signing process to complete.

Personas

The steps described in this tutorial are typically performed by a security engineer.

Challenge

Organizations should protect their website; however, the Traditional PKI process workflow takes a long time, which motivates organizations to create certificates which do not expire for a year or more.

Solution

Use Vault to create X.509 certificates for usage in Mutual Transport Layer Security (MTLS) or other arbitrary PKI encryption. You can use this solution to create web server certificates, but if users do not import the CA chains, browsers will complain about the self-signed certificates.

Creating PKI certificates is generally a cumbersome process using traditional tools like openssl or even more advanced frameworks like CFSSL. These tools also require a human component to verify certificate distribution meets organizational security policies.

Vault's PKI secrets engine makes this a lot simpler. The PKI secrets engine can be an intermediate-only certificate authority, which potentially allows for higher levels of security.

Store CA outside of Vault (air-gapped).
Create CSRs for the intermediate CA.
Sign CSR outside Vault and import intermediate CA.
Issue leaf certificates from the Intermediate CA.

Prerequisites

To perform the tasks described in this tutorial, you need:

A Vault environment. Refer to the Getting Started tutorial to install Vault.
The API and CLI versions of the example scenario use the jq tool to parse JSON output. Install jq in your Vault environment to follow the examples which use this tool.

Launch Terminal

This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.

Policy requirements

Note

For the purposes of this tutorial, you can use a root token to work with Vault. However, it is recommended that root tokens are only used for just enough initial setup or in emergencies. As a best practice, use tokens with appropriate set of policies based on your role in the organization.

To perform all tasks demonstrated in this tutorial, your policy must include the following capabilities:

# Enable secrets engine
path "sys/mounts/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# List enabled secrets engine
path "sys/mounts" {
  capabilities = [ "read", "list" ]
}

# Work with pki secrets engine
path "pki*" {
  capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
}

If you are not familiar with policies, complete the policies tutorial.

Scenario introduction

In this tutorial, you are going to first generate a self-signed root certificate.

Then you are going to generate an intermediate certificate that is signed by the root. You can then create a role and generate a certificate for the test.example.com domain.

You can choose to complete this tutorial at this point or you can continue with the advanced section on multiple issuer functionality beginning with step 7.

There, you will learn how enable a second root CA in the same secrets engine mount. You will also learn how to rotate the older root CA, and begin issuing certificates from the existing role with the new root CA. Finally, you will learn how to sunset the older CA.

In this tutorial, you will perform the following:

Generate Root CA
Generate Intermediate CA
Create a Role
Request Certificates
Revoke Certificates
Remove Expired Certificates
Enable new Root CA (optional)
Rotate older Root CA (optional)
Set default issuer and issue certificate (optional)
Sunset older Root CA (optional)

Notice about multi-issuer functionality

Vault version 1.11.0 and greater allows a single PKI mount to have many Certificate Authority (CA) certificates ("issuers") in a single mount. All issuers within a single mount get treated as a single Authority, meaning that:

Certificate Revocation List (CRL) configuration is common to all issuers/
All authority access URLs are common to all issuers.
Issued certificates' serial numbers will be unique across all issuers.

However, since each issuer may have a distinct subject and keys, different issuers may have different CRLs.

It is strongly encouraged to limit the scope of CAs within a mount and not to mix different types of CAs (roots and intermediates).

Note

Some functionality will not work if a default issuer is not configured. Vault automatically selects the default issuer from the current issuing certificate on migration from an older Vault version (Vault < 1.11.0).

Lab setup

In another terminal, start a Vault dev server with root as the root token.
```
$ vault server -dev -dev-root-token-id root
```
The Vault dev server defaults to running at 127.0.0.1:8200. The server is also initialized and unsealed.

Insecure operation

Do not run a Vault dev server in production. This approach is only used here to simplify the unsealing process for this demonstration.

Export an environment variable for the vault CLI to address the Vault server.
```
$ export VAULT_ADDR=http://127.0.0.1:8200
```
Export an environment variable for the vault CLI to authenticate with the Vault server.
```
$ export VAULT_TOKEN=root
```

The Vault server is ready.

Tip

If you do not have access to an HCP Vault cluster, visit the Create a Vault Cluster on HCP tutorial.

Launch the HCP Portal and login.
Click Vault in the left navigation pane.
In the Vault clusters pane, click vault-cluster.
Under Cluster URLs, click Public Cluster URL.
In a terminal, set the VAULT_ADDR environment variable to the copied address.
```
$ export VAULT_ADDR=<Public_Cluster_URL>
```
Return to the Overview page and click Generate token.
Within a few moments, a new token will be generated.
Copy the Admin Token.
Return to the terminal and set the VAULT_TOKEN environment variable.
```
$ export VAULT_TOKEN=<token>
```
Set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```
The admin namespace is the top-level namespace automatically created by HCP Vault. All CLI operations default to use the namespace defined in this environment variable.

Type vault status to verify your connectivity to the Vault cluster.

$ vault status

Key                      Value
---                      -----
Recovery Seal Type       shamir
Initialized              true
Sealed                   false
Total Recovery Shares    1
Threshold                1
Version                  1.13.0+ent
Storage Type             raft
...snipped...

The HCP Vault server is ready.

Step 1: Generate root CA

In this step, you are going to generate a self-signed root certificate using PKI secrets engine.

Enable the pki secrets engine at the pki path.

$ vault secrets enable pki

Successful output example:

Success! Enabled the pki secrets engine at: pki/

Tune the pki secrets engine to issue certificates with a maximum time-to-live (TTL) of 87600 hours.
```
$ vault secrets tune -max-lease-ttl=87600h pki
```
Successful output example:
```
Success! Tuned the secrets engine at: pki/
```
Generate the example.com root CA, give it an issuer name, and save its certificate in the file root_2022_ca.crt.
```
$ vault write -field=certificate pki/root/generate/internal \
     common_name="example.com" \
     issuer_name="root-2022" \
     ttl=87600h > root_2022_ca.crt
```
This command is not expected to produce any output.
This generates a new self-signed CA certificate and private key. Vault will automatically revoke the generated root at the end of its lease period (TTL); the CA certificate will sign its own Certificate Revocation List (CRL).

List the issuer information for the root CA.

$ vault list pki/issuers/
Keys
----
09c2c9a0-a874-36d2-de85-d79a7a51e373

You can read the issuer with its ID to get the certificates and other metadata about the issuer. Let's skip the certificate output, but list the issuer metadata and usage information.

$ vault read pki/issuer/09c2c9a0-a874-36d2-de85-d79a7a51e373 \
    | tail -n 6

Example output:

leaf_not_after_behavior           err
manual_chain                      <nil>
ocsp_servers                      []
revocation_signature_algorithm    SHA256WithRSA
revoked                           false
usage                             crl-signing,issuing-certificates,ocsp-signing,read-only

Create a role for the root CA; creating this role allows for specifying an issuer when necessary for the purposes of this scenario. This also provides a simple way to transition from one issuer to another by referring to it by name.
```
$ vault write pki/roles/2022-servers allow_any_name=true
Success! Data written to: pki/roles/2022-servers
```
Note
This role is only overly permissive in the names that it allows for the purposes of simplification in this tutorial.

Configure the CA and CRL URLs.

$ vault write pki/config/urls \
     issuing_certificates="$VAULT_ADDR/v1/pki/ca" \
     crl_distribution_points="$VAULT_ADDR/v1/pki/crl"

Successful output example:

Key                        Value
---                        -----
crl_distribution_points    [http://127.0.0.1:8200/v1/pki/crl]
enable_templating          false
issuing_certificates       [http://127.0.0.1:8200/v1/pki/ca]
ocsp_servers               []

Note

When using multiple issuers in the same mount, it is suggested to use the per-issuer AIA fields rather than the global (/config/urls) variant. This is for correctness: these fields are used for chain building and automatic CRL detection in certain applications. If they point to the wrong issuer's information, these applications may break.

Enable the pki secrets engine at pki path using /sys/mounts endpoint.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data '{"type":"pki"}' \
   $VAULT_ADDR/v1/sys/mounts/pki

See the documentation for all available parameters to enable secrets engines.

Tune the pki secrets engine to issue certificates with a maximum time-to-live (TTL) of 87600 hours.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data '{"max_lease_ttl":"87600h"}' \
   $VAULT_ADDR/v1/sys/mounts/pki/tune

Create an API request payload containing the common name to set.

$ tee payload.json <<EOF
{
  "common_name": "example.com",
  "issuer_name": "root-2022",
  "ttl": "87600h"
}
EOF

Generate the root certificate and extract the CA certificate and save it as root_2022_ca.crt.
```
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/pki/root/generate/internal \
   | jq -r ".data.certificate" > root_2022_ca.crt
```
This generates a new self-signed CA certificate and private key. Vault will automatically revoke the generated root at the end of its lease period (TTL); the CA certificate will sign its own Certificate Revocation List (CRL).

List the issuers.

$ curl \
    --silent \
    --header "X-Vault-Request: true" \
    --header "X-Vault-Token: $(vault print token)" \
    http://127.0.0.1:8200/v1/pki/issuers\?list=true \
    | jq

Example output:

{
"request_id": "65f2151a-7b22-b00e-8ae5-b0d5c23e7644",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"key_info": {
  "09c2c9a0-a874-36d2-de85-d79a7a51e373": {
    "is_default": true,
    "issuer_name": "root-2022"
  }
},
"keys": [
  "09c2c9a0-a874-36d2-de85-d79a7a51e373"
]
 },
 "wrap_info": null,
 "warnings": null,
 "auth": null
}

Read the issuer with its ID to get the certificates and other metadata about the issuer. Let's skip the certificate output, but list the issuer metadata and usage information.

$ curl \
    --silent \
    --header "X-Vault-Token: $(vault print token)" \
    --header "X-Vault-Request: true" \
    $VAULT_ADDR/v1/pki/issuer/09c2c9a0-a874-36d2-de85-d79a7a51e373 \
    | jq

Example output:

{
  "request_id": "dff49c60-125e-79f2-5ca0-c1165a196ed9",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDNTCCAh2gAwIBAgIUa1fnttKmxiB1kV8EaWHAVqe1mrEwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTgyMDIzWhcNMzIw\nNjE3MTgyMDUyWjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBALhtn4dJrslD2s00tt9yilRCmtS3/kJWHu/wjkBF\nkCUQ4eba/PhXKHbSntD+XVV+FYZsLLOpvSxJ3htR1ebaXKFbS6VWZRmEtbfmnYoh\nyZZFC0eK+82xa/DDuJsdGa6pMaeFA7RV50LuICZoHDBzlj416HUih8v3wEqdcD16\nb7Pu1Oro3qcj/xBQ9HOQ8qTT/FyWrUgWnk/N6y7BX2fpWYH91aiNjov2QzuFTOer\n8NBJTjqbfIJK5xb9lmuKJZ2P0715UJYhAtdgJaEcOd5pzQw6Wutnh/0Z93ryQozJ\n9Q67+XgRNCDsG6CpfVIc40x7nvC0s0EUCM/hwlgf1tdEBWcCAwEAAaN7MHkwDgYD\nVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFGsBBdaz20yO\nL3NvzkcI5UU0eHWrMB8GA1UdIwQYMBaAFGsBBdaz20yOL3NvzkcI5UU0eHWrMBYG\nA1UdEQQPMA2CC2V4YW1wbGUuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCztaw07tp3\nN7oRV2eiHYnvS0r3667IWqYz0T7+epnN5YuOXSNzjgB8Zbytk2mMKDCLg5mczITi\n/naybO9dczbx2SD9FhQwR3vjy+ykcI5NLjgjQ7EZZO6tyS8ZOjK9igrcp+5XG9fw\nkmp9q64em5ZKYwhR6OP2VgUrgn6MR40BFvhRA5oXH6M+UmYebWNqBB8R2z0BTf+U\nOeO9jpsLDVuhQlis91TKJXTZS6MuZwJB5e8H5/foQXKrrprmKZf2nn95qUApwn7H\nd6y6jaa9zBu8w+HZsamZM9Qi93Vg/5XoGcuTm4XE9zcM2DKPtn79TlrElpdXEH+/\nbs7CfJ5Phq5t\n-----END CERTIFICATE-----\n"
    ],
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDNTCCAh2gAwIBAgIUa1fnttKmxiB1kV8EaWHAVqe1mrEwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTgyMDIzWhcNMzIw\nNjE3MTgyMDUyWjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBALhtn4dJrslD2s00tt9yilRCmtS3/kJWHu/wjkBF\nkCUQ4eba/PhXKHbSntD+XVV+FYZsLLOpvSxJ3htR1ebaXKFbS6VWZRmEtbfmnYoh\nyZZFC0eK+82xa/DDuJsdGa6pMaeFA7RV50LuICZoHDBzlj416HUih8v3wEqdcD16\nb7Pu1Oro3qcj/xBQ9HOQ8qTT/FyWrUgWnk/N6y7BX2fpWYH91aiNjov2QzuFTOer\n8NBJTjqbfIJK5xb9lmuKJZ2P0715UJYhAtdgJaEcOd5pzQw6Wutnh/0Z93ryQozJ\n9Q67+XgRNCDsG6CpfVIc40x7nvC0s0EUCM/hwlgf1tdEBWcCAwEAAaN7MHkwDgYD\nVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFGsBBdaz20yO\nL3NvzkcI5UU0eHWrMB8GA1UdIwQYMBaAFGsBBdaz20yOL3NvzkcI5UU0eHWrMBYG\nA1UdEQQPMA2CC2V4YW1wbGUuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCztaw07tp3\nN7oRV2eiHYnvS0r3667IWqYz0T7+epnN5YuOXSNzjgB8Zbytk2mMKDCLg5mczITi\n/naybO9dczbx2SD9FhQwR3vjy+ykcI5NLjgjQ7EZZO6tyS8ZOjK9igrcp+5XG9fw\nkmp9q64em5ZKYwhR6OP2VgUrgn6MR40BFvhRA5oXH6M+UmYebWNqBB8R2z0BTf+U\nOeO9jpsLDVuhQlis91TKJXTZS6MuZwJB5e8H5/foQXKrrprmKZf2nn95qUApwn7H\nd6y6jaa9zBu8w+HZsamZM9Qi93Vg/5XoGcuTm4XE9zcM2DKPtn79TlrElpdXEH+/\nbs7CfJ5Phq5t\n-----END CERTIFICATE-----\n",
    "issuer_id": "09c2c9a0-a874-36d2-de85-d79a7a51e373",
    "issuer_name": "root-2022",
    "key_id": "4616f6dc-17a4-a137-79b3-82f6b04f38d7",
    "leaf_not_after_behavior": "err",
    "manual_chain": null,
    "usage": "issuing-certificates,crl-signing,read-only"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Create a role for the root CA; creating this role allows for specifying an issuer when necessary for the purposes of this scenario. This also provides a simple way to transition from one issuer to another by referring to it by name.
```
$ curl \
    --silent \
    --request PUT \
    --header "X-Vault-Token: $(vault print token)" \
    --header "X-Vault-Request: true" \
    --data '{"allow_any_name":"true", "issuer_ref": "root-2022"}' \
    http://127.0.0.1:8200/v1/pki/roles/2022-servers
```
This command is not expected to produce any output.
Note
This role is only overly permissive in the names that it allows for the purposes of simplification in this tutorial.

Create an API request payload containing the URLs to set.

$ tee payload-url.json <<EOF
{
  "issuing_certificates": "$VAULT_ADDR/v1/pki/ca",
  "crl_distribution_points": "$VAULT_ADDR/v1/pki/crl"
}
EOF

Configure the CA and CRL URLs.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data @payload-url.json \
   $VAULT_ADDR/v1/pki/config/urls

Note

Enable the pki secrets engine at pki path using /sys/mounts endpoint.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"type":"pki"}' \
   $VAULT_ADDR/v1/sys/mounts/pki

See the documentation for all available parameters to enable secrets engines.

Tune the pki secrets engine to issue certificates with a maximum time-to-live (TTL) of 87600 hours.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"max_lease_ttl":"87600h"}' \
   $VAULT_ADDR/v1/sys/mounts/pki/tune

Create an API request payload containing the common name to set.

$ tee payload.json <<EOF
{
  "common_name": "example.com",
  "issuer_name": "root-2022",
  "ttl": "87600h"
}
EOF

Generate the root certificate and extract the CA certificate and save it as root_2022_ca.crt.
```
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/pki/root/generate/internal \
   | jq -r ".data.certificate" > root_2022_ca.crt
```
This generates a new self-signed CA certificate and private key. Vault will automatically revoke the generated root at the end of its lease period (TTL); the CA certificate will sign its own Certificate Revocation List (CRL).

List the issuers.

$ curl \
    --silent \
    --header "X-Vault-Request: true" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --header "X-Vault-Token: $(vault print token)" \
    http://127.0.0.1:8200/v1/pki/issuers\?list=true \
    | jq

Example output:

{
"request_id": "65f2151a-7b22-b00e-8ae5-b0d5c23e7644",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"key_info": {
  "09c2c9a0-a874-36d2-de85-d79a7a51e373": {
    "is_default": true,
    "issuer_name": "root-2022"
  }
},
"keys": [
  "09c2c9a0-a874-36d2-de85-d79a7a51e373"
]
 },
 "wrap_info": null,
 "warnings": null,
 "auth": null
}

Read the issuer with its ID to get the certificates and other metadata about the issuer. Let's skip the certificate output, but list the issuer metadata and usage information.

$ curl \
    --silent \
    --header "X-Vault-Token: $(vault print token)" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --header "X-Vault-Request: true" \
    $VAULT_ADDR/v1/pki/issuer/09c2c9a0-a874-36d2-de85-d79a7a51e373 \
    | jq

Example output:

{
  "request_id": "dff49c60-125e-79f2-5ca0-c1165a196ed9",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDNTCCAh2gAwIBAgIUa1fnttKmxiB1kV8EaWHAVqe1mrEwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTgyMDIzWhcNMzIw\nNjE3MTgyMDUyWjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBALhtn4dJrslD2s00tt9yilRCmtS3/kJWHu/wjkBF\nkCUQ4eba/PhXKHbSntD+XVV+FYZsLLOpvSxJ3htR1ebaXKFbS6VWZRmEtbfmnYoh\nyZZFC0eK+82xa/DDuJsdGa6pMaeFA7RV50LuICZoHDBzlj416HUih8v3wEqdcD16\nb7Pu1Oro3qcj/xBQ9HOQ8qTT/FyWrUgWnk/N6y7BX2fpWYH91aiNjov2QzuFTOer\n8NBJTjqbfIJK5xb9lmuKJZ2P0715UJYhAtdgJaEcOd5pzQw6Wutnh/0Z93ryQozJ\n9Q67+XgRNCDsG6CpfVIc40x7nvC0s0EUCM/hwlgf1tdEBWcCAwEAAaN7MHkwDgYD\nVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFGsBBdaz20yO\nL3NvzkcI5UU0eHWrMB8GA1UdIwQYMBaAFGsBBdaz20yOL3NvzkcI5UU0eHWrMBYG\nA1UdEQQPMA2CC2V4YW1wbGUuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCztaw07tp3\nN7oRV2eiHYnvS0r3667IWqYz0T7+epnN5YuOXSNzjgB8Zbytk2mMKDCLg5mczITi\n/naybO9dczbx2SD9FhQwR3vjy+ykcI5NLjgjQ7EZZO6tyS8ZOjK9igrcp+5XG9fw\nkmp9q64em5ZKYwhR6OP2VgUrgn6MR40BFvhRA5oXH6M+UmYebWNqBB8R2z0BTf+U\nOeO9jpsLDVuhQlis91TKJXTZS6MuZwJB5e8H5/foQXKrrprmKZf2nn95qUApwn7H\nd6y6jaa9zBu8w+HZsamZM9Qi93Vg/5XoGcuTm4XE9zcM2DKPtn79TlrElpdXEH+/\nbs7CfJ5Phq5t\n-----END CERTIFICATE-----\n"
    ],
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDNTCCAh2gAwIBAgIUa1fnttKmxiB1kV8EaWHAVqe1mrEwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTgyMDIzWhcNMzIw\nNjE3MTgyMDUyWjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBALhtn4dJrslD2s00tt9yilRCmtS3/kJWHu/wjkBF\nkCUQ4eba/PhXKHbSntD+XVV+FYZsLLOpvSxJ3htR1ebaXKFbS6VWZRmEtbfmnYoh\nyZZFC0eK+82xa/DDuJsdGa6pMaeFA7RV50LuICZoHDBzlj416HUih8v3wEqdcD16\nb7Pu1Oro3qcj/xBQ9HOQ8qTT/FyWrUgWnk/N6y7BX2fpWYH91aiNjov2QzuFTOer\n8NBJTjqbfIJK5xb9lmuKJZ2P0715UJYhAtdgJaEcOd5pzQw6Wutnh/0Z93ryQozJ\n9Q67+XgRNCDsG6CpfVIc40x7nvC0s0EUCM/hwlgf1tdEBWcCAwEAAaN7MHkwDgYD\nVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFGsBBdaz20yO\nL3NvzkcI5UU0eHWrMB8GA1UdIwQYMBaAFGsBBdaz20yOL3NvzkcI5UU0eHWrMBYG\nA1UdEQQPMA2CC2V4YW1wbGUuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCztaw07tp3\nN7oRV2eiHYnvS0r3667IWqYz0T7+epnN5YuOXSNzjgB8Zbytk2mMKDCLg5mczITi\n/naybO9dczbx2SD9FhQwR3vjy+ykcI5NLjgjQ7EZZO6tyS8ZOjK9igrcp+5XG9fw\nkmp9q64em5ZKYwhR6OP2VgUrgn6MR40BFvhRA5oXH6M+UmYebWNqBB8R2z0BTf+U\nOeO9jpsLDVuhQlis91TKJXTZS6MuZwJB5e8H5/foQXKrrprmKZf2nn95qUApwn7H\nd6y6jaa9zBu8w+HZsamZM9Qi93Vg/5XoGcuTm4XE9zcM2DKPtn79TlrElpdXEH+/\nbs7CfJ5Phq5t\n-----END CERTIFICATE-----\n",
    "issuer_id": "09c2c9a0-a874-36d2-de85-d79a7a51e373",
    "issuer_name": "root-2022",
    "key_id": "4616f6dc-17a4-a137-79b3-82f6b04f38d7",
    "leaf_not_after_behavior": "err",
    "manual_chain": null,
    "usage": "issuing-certificates,crl-signing,read-only"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Create a role for the root CA; creating this role allows for specifying an issuer when necessary for the purposes of this scenario. This also provides a simple way to transition from one issuer to another by referring to it by name.
```
$ curl \
    --silent \
    --request PUT \
    --header "X-Vault-Token: $(vault print token)" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --header "X-Vault-Request: true" \
    --data '{"allow_any_name":"true", "issuer_ref": "root-2022"}' \
    http://127.0.0.1:8200/v1/pki/roles/2022-servers
```
This command is not expected to produce any output.
Note
This role is only overly permissive in the names that it allows for the purposes of simplification in this tutorial.

Create an API request payload containing the URLs to set.

$ tee payload-url.json <<EOF
{
  "issuing_certificates": "$VAULT_ADDR/v1/pki/ca",
  "crl_distribution_points": "$VAULT_ADDR/v1/pki/crl"
}
EOF

Configure the CA and CRL URLs.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @payload-url.json \
   $VAULT_ADDR/v1/pki/config/urls

Note

Open a web browser and launch the Vault UI.
Login by entering the root (for Vault in dev mode) or the admin token (for HCP Vault) in the Token field.
Select Enable new engine.
Select PKI Certificates from the list, and then click Next.
Expand Method Options.
Enable Max Lease TTL and set the value to 87600 hours.
Click Enable Engine to complete. This sets the path to be pki.
Select the Configuration tab and then Configure.
Click Configure CA.
Ensure that the CA Type is set to root.
Ensure that the Type is set to internal.
Enter example.com in the Common name field.
Expand Options.
Enable TTL and set the value to 87600 hours.
Click Save.
Click Copy Certificate and save it in a file named root_2022_ca.crt.
Click the URLs tab.
Enter <VAULT-ADDRESS:PORT>/v1/pki/ca in the Issuing certificates field.
Enter <VAULT-ADDRESS:PORT>/v1/pki/crl in the CRL Distribution Points field.
Click Save.
Add a role to the root CA for convenience in this scenario when rotating the root CA.
Click pki
Click Create role
Enter 2022-servers into the Role name field.
Click Create role

OpenSSL enables you to view all the metadata of the generated certificate.

Print the certificate in text form.

$ openssl x509 -in root_2022_ca.crt -text

Step 2: Generate intermediate CA

Now, you are going to create an intermediate CA using the root CA you regenerated in the previous step.

Tip

If you have Vault version 1.13.0 or later, you can use the new CLI helper pki issue to generate your intermediate CA. Follow the steps in the pki issue command tab to use the helper instead of the standard CLI workflow.

First, enable the pki secrets engine at the pki_int path.

$ vault secrets enable -path=pki_int pki

Successful output example:

Success! Enabled the pki secrets engine at: pki_int/

Tune the pki_int secrets engine to issue certificates with a maximum time-to-live (TTL) of 43800 hours.
```
$ vault secrets tune -max-lease-ttl=43800h pki_int
```
Successful output example:
```
Success! Tuned the secrets engine at: pki_int/
```

Execute the following command to generate an intermediate and save the CSR as pki_intermediate.csr.

$ vault write -format=json pki_int/intermediate/generate/internal \
     common_name="example.com Intermediate Authority" \
     issuer_name="example-dot-com-intermediate" \
     | jq -r '.data.csr' > pki_intermediate.csr

This command is expected to produce no output.

Sign the intermediate certificate with the root CA private key, and save the generated certificate as intermediate.cert.pem.

$ vault write -format=json pki/root/sign-intermediate \
     issuer_ref="root-2022" \
     csr=@pki_intermediate.csr \
     format=pem_bundle ttl="43800h" \
     | jq -r '.data.certificate' > intermediate.cert.pem

This command is expected to produce no output.

Once the CSR is signed and the root CA returns a certificate, it can be imported back into Vault.

$ vault write pki_int/intermediate/set-signed certificate=@intermediate.cert.pem

Successful output example:

Key                 Value
---                 -----
imported_issuers    [ffefa5b2-ae7c-b765-1672-c275fec29dc7 276a666f-c8da-20c5-c5a4-e01dff8ff2ea]
imported_keys       <nil>
mapping             map[276a666f-c8da-20c5-c5a4-e01dff8ff2ea: ffefa5b2-ae7c-b765-1672-c275fec29dc7:0f021093-a446-5b8e-70e8-a6bbda6f1a99]

Enable the pki secrets engine at the pki_int path.

$ vault secrets enable -path=pki_int pki

Successful output example:

Success! Enabled the pki secrets engine at: pki_int/

Tune the pki_int secrets engine to issue certificates with a maximum time-to-live (TTL) of 43800 hours.
```
$ vault secrets tune -max-lease-ttl=43800h pki_int
```
Successful output example:
```
Success! Tuned the secrets engine at: pki_int/
```

Use the pki issue command to handle the intermediate CA generation process for you. The example parameters match this PKI secrets engine instance in this tutorial.

$ vault pki issue \
      --issuer_name=example-dot-com-intermediate \
      /pki/issuer/a13b7db8-58f2-d926-64fc-bd39c9e6950c \
      /pki_int/ \
      common_name="example.com Intermediate Authority" \
      o="example" \
      ou="education" \
      key_type="rsa" \
      key_bits="4096" \
      max_depth_len=1 \
      permitted_dns_domains="test.example.com" \
      ttl="1440m"

Abbreviated output example:

Key                               Value
---                               -----
ca_chain                          [-----BEGIN CERTIFICATE-----
MIIE3jCCA8agAwIBAgIUWR5g4+h92GL/7DndQfaecf3DoZIwDQYJKoZIhvcNAQEL
...snip...
crl_distribution_points           []
issuer_id                         e48e21f4-7690-9c3c-acb8-2d60450f4150
issuer_name                       example-dot-com-intermediate
issuing_certificates              []
key_id                            d50faa6c-1f3c-e197-a205-16e6903c64f7
leaf_not_after_behavior           err
manual_chain                      <nil>
ocsp_servers                      []
revocation_signature_algorithm    n/a
revoked                           false
usage                             crl-signing,issuing-certificates,ocsp-signing,read-only

Enable the pki secrets engine at pki_int path.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data '{"type":"pki"}' \
   $VAULT_ADDR/v1/sys/mounts/pki_int

Tune the pki_int secrets engine to issue certificates with a maximum time-to-live (TTL) of 43800 hours.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data '{"max_lease_ttl":"43800h"}' \
   $VAULT_ADDR/v1/sys/mounts/pki_int/tune

Create an API request payload containing the common name to set.

$ tee payload-int.json <<EOF
{
  "common_name": "example.com Intermediate Authority",
  "issuer_name": "example-dot-com-intermediate"
}
EOF

Generate an intermediate using the /pki_int/intermediate/generate/internal endpoint and save it as pki_intermediate.csr.

$ curl \
    --silent \
    --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data @payload-int.json \
    $VAULT_ADDR/v1/pki_int/intermediate/generate/internal \
    | jq -c '.data | .csr' >> pki_intermediate.csr

Create an API request payload to sign the CSR.

$ tee payload-int-cert.json <<EOF
{
  "csr": $(cat pki_intermediate.csr),
  "format": "pem_bundle",
  "ttl": "43800h"
}
EOF

Sign the intermediate certificate with the root CA private key, and save the certificate as intermediate.cert.pem.

$ curl \
    --silent \
    --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data @payload-int-cert.json \
    $VAULT_ADDR/v1/pki/root/sign-intermediate \
    | jq '.data | .certificate' >> intermediate.cert.pem

Note

The format in the payload specifies the format of the returned data. When pem_bundle, the certificate field will contain the certificate.

Once the CSR is signed and the root CA returns a certificate, it can be imported back into Vault using the /pki_int/intermediate/set-signed endpoint.
Create an API request payload containing the certificate you obtained.
```
$ tee payload-signed.json <<EOF
{
  "certificate": $(cat intermediate.cert.pem)
}
EOF
```

Submit the signed certificate.

$ curl \
    --silent \
    --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data @payload-signed.json \
    $VAULT_ADDR/v1/pki_int/intermediate/set-signed \
    | jq

Example output:

{
  "request_id": "bf5baa70-29c1-8914-8b0d-77dac716e0c4",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "imported_issuers": null,
    "imported_keys": null,
    "mapping": {
      "29ec3886-e47f-6ceb-7086-a14f9cf54167": "",
      "59dea688-a8f5-1893-9c46-0013914ce7e4": "43b44883-5423-5908-8e56-b690e543568a"
    }
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Enable the pki secrets engine at pki_int path.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"type":"pki"}' \
   $VAULT_ADDR/v1/sys/mounts/pki_int

Tune the pki_int secrets engine to issue certificates with a maximum time-to-live (TTL) of 43800 hours.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"max_lease_ttl":"43800h"}' \
   $VAULT_ADDR/v1/sys/mounts/pki_int/tune

Create an API request payload containing the common name to set.

$ tee payload-int.json <<EOF
{
  "common_name": "example.com Intermediate Authority",
  "issuer_name": "example-dot-com-intermediate"
}
EOF

Generate an intermediate using the /pki_int/intermediate/generate/internal endpoint and save it as pki_intermediate.csr.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @payload-int.json \
   $VAULT_ADDR/v1/pki_int/intermediate/generate/internal | jq -c '.data | .csr' >> pki_intermediate.csr

Create an API request payload to sign the CSR.

$ tee payload-int-cert.json <<EOF
{
  "csr": $(cat pki_intermediate.csr),
  "format": "pem_bundle",
  "ttl": "43800h"
}
EOF

Sign the intermediate certificate with the root CA private key, and save the certificate as intermediate.cert.pem.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @payload-int-cert.json \
   $VAULT_ADDR/v1/pki/root/sign-intermediate | jq '.data | .certificate' >> intermediate.cert.pem

Note

The format in the payload specifies the format of the returned data. When pem_bundle, the certificate field will contain the certificate.

Once the CSR is signed and the root CA returns a certificate, it can be imported back into Vault using the /pki_int/intermediate/set-signed endpoint.
Create an API request payload containing the certificate you obtained.
```
$ tee payload-signed.json <<EOF
{
  "certificate": $(cat intermediate.cert.pem)
}
EOF
```

Submit the signed certificate.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @payload-signed.json \
   $VAULT_ADDR/v1/pki_int/intermediate/set-signed

From Secrets, select Enable new engine.
Select the PKI Certificates radio button, and click Next.
Enter pki_int in the Path field.
Click More options to expand and set the Maximum lease TTL to 43800 hours.
Click Enable Engine.
Select the Configuration tab and then Configure.
Click Configure CA.
Select intermediate from CA Type drop-down list.
Enter example.com Intermediate Authority in the Common name field.
Click Save.
Click Copy CSR and save it in a file, pki_intermediate.csr.
Return to the pki in the Secrets tab which is the root CA.
Select the Configuration tab and then Configure.
Click Sign intermediate.
Paste in the CSR you just copied into the Certificate Signing Request (CSR) field.
Enter example.com in the Common name.
Select pem_bundle from the Format drop-down list, and then click Save.
Click Copy Certificate and save the generated certificate in a file, intermediate.cert.pem.
Select pki_int from the Secrets tab to return to the intermediate CA.
Select the Configuration tab and then Configure.
Click Set signed intermediate.
Paste in the certificate in the Signed Intermediate Certificate field and then click Save.

Step 3: Create a role

A role is a logical name that maps to a policy used to generate those credentials. It allows configuration parameters to control certificate common names, alternate names, the key uses that they are valid for, and more.

Here are a few noteworthy parameters:

Param	Description
`allowed_domains`	Specifies the domains of the role (used with `allow_bare_domains` and `allow-subdomains` options)
`allow_bare_domains`	Specifies if clients can request certificates matching the value of the actual domains themselves
`allow_subdomains`	Specifies if clients can request certificates with CNs that are subdomains of the CNs allowed by the other role options (NOTE: This includes wildcard subdomains.)
`allow_glob_domains`	Allows names specified in allowed_domains to contain glob patterns (e.g. ftp*.example.com)

In this step, you are going to create a role named example-dot-com.

Create a role named example-dot-com which allows subdomains, and specify the default issuer ref ID as the value of issuer_ref.

$ vault write pki_int/roles/example-dot-com \
     issuer_ref="$(vault read -field=default pki_int/config/issuers)" \
     allowed_domains="example.com" \
     allow_subdomains=true \
     max_ttl="720h"

Create an API request payload containing domain information to set.

$ tee payload-role.json <<EOF
{
  "allowed_domains": "example.com",
  "allow_subdomains": true,
  "issuer_ref": "$(vault read -field=default pki_int/config/issuers)",
  "max_ttl": "720h"
}
EOF

Create a role named example-dot-com which allows subdomains.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data @payload-role.json \
   $VAULT_ADDR/v1/pki_int/roles/example-dot-com

Create an API request payload containing domain information to set.

$ tee payload-role.json <<EOF
{
  "allowed_domains": "example.com",
  "allow_subdomains": true,
  "issuer_ref": "$(vault read -field=default pki_int/config/issuers)",
  "max_ttl": "720h"
}
EOF

Create a role named example-dot-com which allows subdomains.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @payload-role.json \
   $VAULT_ADDR/v1/pki_int/roles/example-dot-com

Create a role named example-dot-com which allows subdomains.

Click the terminal icon.
In terminal, use the following command to list issuers:
```
read -field=default pki_int/config/issuers
```
Copy the value from the above command.
Click pki_int and then select Create role.
Enter example-dot-com in the Role name field.
Paste the value you copied in step 3 into the Issuer ref field.
Expand Options and then set the Max TTL to 43800 hours (5 years).
Select Hide Options.
Expand Domain Handling and then select the Allow subdomains check-box. Enter example.com in the Allowed domains field.
Click Create role.

Step 4: Request certificates

Keep certificate lifetimes short to align with Vault's philosophy of short-lived secrets.

Execute the following command to request a new certificate for the test.example.com domain based on the example-dot-com role.

$ vault write pki_int/issue/example-dot-com common_name="test.example.com" ttl="24h"

Key                 Value
---                 -----
certificate         -----BEGIN CERTIFICATE-----
MIIDwzCCAqugAwIBAgIUTQABMCAsXjG6ExFTX8201xKVH4IwDQYJKoZIhvcNAQEL
BQAwGjEYMBYGA1UEAxMPd3d3LmV4YW1wbGUuY29tMB4XDTE4MDcyNDIxMTMxOVoX
             ...

-----END CERTIFICATE-----
issuing_ca          -----BEGIN CERTIFICATE-----
MIIDQTCCAimgAwIBAgIUbMYp39mdj7dKX033ZjK18rx05x8wDQYJKoZIhvcNAQEL
             ...

-----END CERTIFICATE-----
private_key         -----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAte1fqy2Ekj+EFqKV6N5QJlBgMo/U4IIxwLZI6a87yAC/rDhm
W58liadXrwjzRgWeqVOoCRr/B5JnRLbyIKBVp6MMFwZVkynEPzDmy0ynuomSfJkM
             ...

-----END RSA PRIVATE KEY-----
private_key_type    rsa
serial_number       4d:00:01:30:20:2c:5e:31:ba:13:11:53:5f:cd:b4:d7:12:95:1f:82

The response contains the PEM-encoded private key, key type and certificate serial number.

Invoke the /pki_int/issue/<role_name> endpoint to request a new certificate.

Request a certificate for the test.example.com domain based on the example-dot-com role.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{"common_name": "test.example.com", "ttl": "24h"}' \
    $VAULT_ADDR/v1/pki_int/issue/example-dot-com | jq

Here is a complete example output.

{
  "request_id": "7544fb94-49aa-8a11-1396-67938b69c3f2",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDqDCCApCgAwIBAgIUfg7l07KVEnht4ETStjHLAA3xvp4wDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjEwNDE5MTYzNTM1WhcNMjYw\nNDE4MTYzNjA1WjAtMSswKQYDVQQDEyJleGFtcGxlLmNvbSBJbnRlcm1lZGlhdGUg\nQXV0aG9yaXR5MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApranvA5f\ncP+OySUE+uKNxzR3IkWI59Z0mMYlHYBtAY47V8avXcmwsaFDJiGSq6OXJs8SXKiF\nrXONaQSudWxTO28U8AovcwoV3/C5KsldqbhLMOyor+XDWYQP7GVXGuKYhn9C+kaF\nbiyaPE0SsAb6Yl3emVl1UCq9kBbQm1XmFyih7rdREB4XJZW2Mtp5KdzlHf3zGLfB\nEcK/BF0CsC1kI5UkkJVWxLB3hKx2pr3Bl3olufQDDdweKqlg7YtiPPnmxLvuEq5n\nG5h18++mbxywIvU7iehGYDj+EBFV1zrsOmZcqfSC34xRbJLVg8wFhuQ59Zy/k+mh\nEUo63NOrT1lzTQIDAQABo4HWMIHTMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8E\nBTADAQH/MB0GA1UdDgQWBBQoQnqjxjJ8ExU3SDHRG9M67KNlLDAfBgNVHSMEGDAW\ngBSnG76ILbfk2VdLrRd6m6bVYK3qRjA8BggrBgEFBQcBAQQwMC4wLAYIKwYBBQUH\nMAKGIGh0dHBzOi8vMTI3LjAuMC4xOjgyMDAvdjEvcGtpL2NhMDIGA1UdHwQrMCkw\nJ6AloCOGIWh0dHBzOi8vMTI3LjAuMC4xOjgyMDAvdjEvcGtpL2NybDANBgkqhkiG\n9w0BAQsFAAOCAQEAegVUIb5SFR/bXo33xqjuocINJLfec22dgjgBO0lMOGp32GFB\nIp4clgfNU1Dw8yGQEoRQHEfWDjZeGdPuCYbgu/ucLW1pLrBiQqO/XgVeFQhwnJp6\nza0NLGnmaDd5k8z1+VJ79tJa0Wb2WRxWxYqu6lsqtYPAj9jD4DM73tfGR76/rCiK\nRB9DRwlr9UTm9h0cw84UpPwaX33kfiIKBeyY9/hUe3pBzGuNGuDgjOiaMph0v+9z\nwiyNCzcR0AN0y1qDVvsqABH9GJ0BpaZ48GbZTZm91Q/kg+HdNlPkgwqpY8+V8aMa\n1CyvvvJeega8q9Evg1v68MajkFFT37YI5XESCw==\n-----END CERTIFICATE-----"
    ],
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDZjCCAk6gAwIBAgIUPwOpEOAo39zYqPlQe83UjAH1R14wDQYJKoZIhvcNAQEL\nBQAwLTErMCkGA1UEAxMiZXhhbXBsZS5jb20gSW50ZXJtZWRpYXRlIEF1dGhvcml0\neTAeFw0yMTA0MTkxNjM5MjVaFw0yMTA0MjAxNjM5NTVaMBsxGTAXBgNVBAMTEHRl\nc3QuZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDP\nfe4nVV+AFnRUgW33qXyCOC4y7ruzSm9P6SiEirTFT+MmNtHEGPBGImGFBLYrSqMo\nePiO3GolpHWezY73cvRzFWM/ZLTmfjqsFNsQmP4tS1bbKa7Bn2ZcypbJNENr+/d1\nBkv9mIJuJwI1sQLI2yQe8KZT3HLrtr4tbEGXnY/tZD3rm+kgZNvCq0GpTARATCkZ\n3qUgOT10O5dMYe8Y2GGCZisiviKeGP1S42EL15QsoLhvIui2sZws7sa6LLeWMNYM\nIsWRAYsTkDffFRWEx/yK1axr0Heo9TrRVBuNfRkU8X/p1Ls3kXUB/HMF9RsW53uZ\nDPJbXOHDSJVhkubPoDxXAgMBAAGjgY8wgYwwDgYDVR0PAQH/BAQDAgOoMB0GA1Ud\nJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQU0UKGmwpRpQsi+wTo\nviMS6w6iEkowHwYDVR0jBBgwFoAUKEJ6o8YyfBMVN0gx0RvTOuyjZSwwGwYDVR0R\nBBQwEoIQdGVzdC5leGFtcGxlLmNvbTANBgkqhkiG9w0BAQsFAAOCAQEAhRcjJf6T\nve9hrVsYSVZLGEOmfYoVJ9J2u7fxOfIMnBYJ0EEm047my6Qj5wmu00HSefhheBK1\n46XK5iBlpdSVrV28IjE8PDnWotWVyYhy9vq+LdVbrhHV3JWbRtM21AXkL/73dB3h\nBC3o+lRjmw+ySSEFlfugP+a9ULqwWtuQH+uFWq86F2Ar4y5Sl4TnIiZ9i22Yx+i4\nKcwPRPFsEyCvwRh1Ih/r/UTsrF0lqE7iQ77Yo9I9MuNKMc6y3+fI3vZWTED0QIfz\nVlb+A5Q9AfGhfaygc2fzJ9w/gnZ+D6wp/mQWQz2xNxs3iaDQf8xHpXywYNGbkVXX\ny/cTj/D8a8iAJA==\n-----END CERTIFICATE-----",
    "expiration": 1618936795,
    "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDqDCCApCgAwIBAgIUfg7l07KVEnht4ETStjHLAA3xvp4wDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjEwNDE5MTYzNTM1WhcNMjYw\nNDE4MTYzNjA1WjAtMSswKQYDVQQDEyJleGFtcGxlLmNvbSBJbnRlcm1lZGlhdGUg\nQXV0aG9yaXR5MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApranvA5f\ncP+OySUE+uKNxzR3IkWI59Z0mMYlHYBtAY47V8avXcmwsaFDJiGSq6OXJs8SXKiF\nrXONaQSudWxTO28U8AovcwoV3/C5KsldqbhLMOyor+XDWYQP7GVXGuKYhn9C+kaF\nbiyaPE0SsAb6Yl3emVl1UCq9kBbQm1XmFyih7rdREB4XJZW2Mtp5KdzlHf3zGLfB\nEcK/BF0CsC1kI5UkkJVWxLB3hKx2pr3Bl3olufQDDdweKqlg7YtiPPnmxLvuEq5n\nG5h18++mbxywIvU7iehGYDj+EBFV1zrsOmZcqfSC34xRbJLVg8wFhuQ59Zy/k+mh\nEUo63NOrT1lzTQIDAQABo4HWMIHTMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8E\nBTADAQH/MB0GA1UdDgQWBBQoQnqjxjJ8ExU3SDHRG9M67KNlLDAfBgNVHSMEGDAW\ngBSnG76ILbfk2VdLrRd6m6bVYK3qRjA8BggrBgEFBQcBAQQwMC4wLAYIKwYBBQUH\nMAKGIGh0dHBzOi8vMTI3LjAuMC4xOjgyMDAvdjEvcGtpL2NhMDIGA1UdHwQrMCkw\nJ6AloCOGIWh0dHBzOi8vMTI3LjAuMC4xOjgyMDAvdjEvcGtpL2NybDANBgkqhkiG\n9w0BAQsFAAOCAQEAegVUIb5SFR/bXo33xqjuocINJLfec22dgjgBO0lMOGp32GFB\nIp4clgfNU1Dw8yGQEoRQHEfWDjZeGdPuCYbgu/ucLW1pLrBiQqO/XgVeFQhwnJp6\nza0NLGnmaDd5k8z1+VJ79tJa0Wb2WRxWxYqu6lsqtYPAj9jD4DM73tfGR76/rCiK\nRB9DRwlr9UTm9h0cw84UpPwaX33kfiIKBeyY9/hUe3pBzGuNGuDgjOiaMph0v+9z\nwiyNCzcR0AN0y1qDVvsqABH9GJ0BpaZ48GbZTZm91Q/kg+HdNlPkgwqpY8+V8aMa\n1CyvvvJeega8q9Evg1v68MajkFFT37YI5XESCw==\n-----END CERTIFICATE-----",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAz33uJ1VfgBZ0VIFt96l8gjguMu67s0pvT+kohIq0xU/jJjbR\nxBjwRiJhhQS2K0qjKHj4jtxqJaR1ns2O93L0cxVjP2S05n46rBTbEJj+LUtW2ymu\nwZ9mXMqWyTRDa/v3dQZL/ZiCbicCNbECyNskHvCmU9xy67a+LWxBl52P7WQ965vp\nIGTbwqtBqUwEQEwpGd6lIDk9dDuXTGHvGNhhgmYrIr4inhj9UuNhC9eULKC4byLo\ntrGcLO7Guiy3ljDWDCLFkQGLE5A33xUVhMf8itWsa9B3qPU60VQbjX0ZFPF/6dS7\nN5F1AfxzBfUbFud7mQzyW1zhw0iVYZLmz6A8VwIDAQABAoIBADMwNhiuDyliYMCY\nTbDTt0vI4FzgWJ4atutX8g8AySgEVV2QGJ/wJxamVLikOOzlNOs/LNLRvb4bnIjY\n3XRef8AEfr+c8KQMcB0T6BdoJwy1kW/wEJTj5jTuJdTtd9SkDKBqNUUS4tqZ9QmZ\n6b3zki2v4Ni/gfp00uYR1vy4elFt/yjTmA0lhY4onPNPqXNWCF1LY38xNegBQZg4\nrYkSFvIOr7bl7Rk2JljWCxZZef5kEIFGdoqus5KekzW8Li9s2XVVXWEfoY/r/NI1\nHgAwHugwe3+8ve3YKLIIKJqGvYk+8Lp8rXPsf9GRZxpxx/yER4NX8+83DndBnfQO\n7G/BOwECgYEA/0ZAU6h+1cW+PxQ+CuSdbClXhKgqTN4pRwCbrGUQ3y2KGsGUzZW/\nUuO/XIN/hkx0SkKz10TvUV5o4SXh5nY7s+3OCsnc7fBx3Gv4vHCWQ4t9JNxeH6vP\nzNKjQeceVzlniyxKlW9OvVDXZU6nv27LBRH1fIYp9QRbc7yHzUQXLCcCgYEA0BTp\nD3CXELJYoV0/LFvRQqZ+P1Xo26qa9xjRMI+Owr2nNuzqcMl4dBvZWNNCpDwqrKn6\n6iiWXYhwxvvKkJe9QgE3LCvkmluGiBDpK4U2rVbB/LoBAtNgGdnxaP9t9OfhtQC3\nPjhVJvBVbk3mFWG950Ua5E1cgl6n4xtGoHgxHFECgYBaXOTieE/FnoUU0TaRJpIv\nOoc3d0vZ//5+mtGAeho51mX/yKzDBZI/Zk1UE1xuDtxPeUMuHcHVfOUFZiKMMSg7\nLh/0o7ZoJ+g2TaY0FmqqqFL5XGSZM3mQmLOf3Y9Y8wIbOud/9HHcBCTrQKeS1UZa\nmhvbI6bwi8VPt9oeqE7HmwKBgHqOVlbJsbAb2yfvi+3MhowDFAipyOTYrz0qWMuJ\nQkRg/8PR9qNHhrKcVH+ErpOc/GWGGEsibK3aVtJcKwrO1KGzpZNWpuZjUfGCRFNl\nuraNiuQXidDoPon7W7zD9Tdx+/Zn3YXAGCc/FpJJP2MIlplIknY1Om9u4ONahVau\nc/6BAoGBAIfW6PPFjXUUn3LvcswvQAahnclYIW+Ml6peerfMr5kq0TTWykrMN4nc\nLl9oGG2ifigSUo/mz2cfemExO+hgXJP+UOOKi2LkUUpV9x1fzJFHYutiIyV4mBPd\nTFPCpLJjz3T4Nn18nzGmrQiQT6ymgt4KDx6cW+xbOLTuNsNg+0ib\n-----END RSA PRIVATE KEY-----",
    "private_key_type": "rsa",
    "serial_number": "3f:03:a9:10:e0:28:df:dc:d8:a8:f9:50:7b:cd:d4:8c:01:f5:47:5e"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

The response contains the PEM-encoded private key, key type and certificate serial number.

Request a certificate for the test.example.com domain based on the example-dot-com role.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"common_name": "test.example.com", "ttl": "24h"}' \
   $VAULT_ADDR/v1/pki_int/issue/example-dot-com | jq

Example output.

{
  "request_id": "7544fb94-49aa-8a11-1396-67938b69c3f2",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDqDCCApCgAwIBAgIUfg7l07KVEnht4ETStjHLAA3xvp4wDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjEwNDE5MTYzNTM1WhcNMjYw\nNDE4MTYzNjA1WjAtMSswKQYDVQQDEyJleGFtcGxlLmNvbSBJbnRlcm1lZGlhdGUg\nQXV0aG9yaXR5MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApranvA5f\ncP+OySUE+uKNxzR3IkWI59Z0mMYlHYBtAY47V8avXcmwsaFDJiGSq6OXJs8SXKiF\nrXONaQSudWxTO28U8AovcwoV3/C5KsldqbhLMOyor+XDWYQP7GVXGuKYhn9C+kaF\nbiyaPE0SsAb6Yl3emVl1UCq9kBbQm1XmFyih7rdREB4XJZW2Mtp5KdzlHf3zGLfB\nEcK/BF0CsC1kI5UkkJVWxLB3hKx2pr3Bl3olufQDDdweKqlg7YtiPPnmxLvuEq5n\nG5h18++mbxywIvU7iehGYDj+EBFV1zrsOmZcqfSC34xRbJLVg8wFhuQ59Zy/k+mh\nEUo63NOrT1lzTQIDAQABo4HWMIHTMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8E\nBTADAQH/MB0GA1UdDgQWBBQoQnqjxjJ8ExU3SDHRG9M67KNlLDAfBgNVHSMEGDAW\ngBSnG76ILbfk2VdLrRd6m6bVYK3qRjA8BggrBgEFBQcBAQQwMC4wLAYIKwYBBQUH\nMAKGIGh0dHBzOi8vMTI3LjAuMC4xOjgyMDAvdjEvcGtpL2NhMDIGA1UdHwQrMCkw\nJ6AloCOGIWh0dHBzOi8vMTI3LjAuMC4xOjgyMDAvdjEvcGtpL2NybDANBgkqhkiG\n9w0BAQsFAAOCAQEAegVUIb5SFR/bXo33xqjuocINJLfec22dgjgBO0lMOGp32GFB\nIp4clgfNU1Dw8yGQEoRQHEfWDjZeGdPuCYbgu/ucLW1pLrBiQqO/XgVeFQhwnJp6\nza0NLGnmaDd5k8z1+VJ79tJa0Wb2WRxWxYqu6lsqtYPAj9jD4DM73tfGR76/rCiK\nRB9DRwlr9UTm9h0cw84UpPwaX33kfiIKBeyY9/hUe3pBzGuNGuDgjOiaMph0v+9z\nwiyNCzcR0AN0y1qDVvsqABH9GJ0BpaZ48GbZTZm91Q/kg+HdNlPkgwqpY8+V8aMa\n1CyvvvJeega8q9Evg1v68MajkFFT37YI5XESCw==\n-----END CERTIFICATE-----"
    ],
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDZjCCAk6gAwIBAgIUPwOpEOAo39zYqPlQe83UjAH1R14wDQYJKoZIhvcNAQEL\nBQAwLTErMCkGA1UEAxMiZXhhbXBsZS5jb20gSW50ZXJtZWRpYXRlIEF1dGhvcml0\neTAeFw0yMTA0MTkxNjM5MjVaFw0yMTA0MjAxNjM5NTVaMBsxGTAXBgNVBAMTEHRl\nc3QuZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDP\nfe4nVV+AFnRUgW33qXyCOC4y7ruzSm9P6SiEirTFT+MmNtHEGPBGImGFBLYrSqMo\nePiO3GolpHWezY73cvRzFWM/ZLTmfjqsFNsQmP4tS1bbKa7Bn2ZcypbJNENr+/d1\nBkv9mIJuJwI1sQLI2yQe8KZT3HLrtr4tbEGXnY/tZD3rm+kgZNvCq0GpTARATCkZ\n3qUgOT10O5dMYe8Y2GGCZisiviKeGP1S42EL15QsoLhvIui2sZws7sa6LLeWMNYM\nIsWRAYsTkDffFRWEx/yK1axr0Heo9TrRVBuNfRkU8X/p1Ls3kXUB/HMF9RsW53uZ\nDPJbXOHDSJVhkubPoDxXAgMBAAGjgY8wgYwwDgYDVR0PAQH/BAQDAgOoMB0GA1Ud\nJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQU0UKGmwpRpQsi+wTo\nviMS6w6iEkowHwYDVR0jBBgwFoAUKEJ6o8YyfBMVN0gx0RvTOuyjZSwwGwYDVR0R\nBBQwEoIQdGVzdC5leGFtcGxlLmNvbTANBgkqhkiG9w0BAQsFAAOCAQEAhRcjJf6T\nve9hrVsYSVZLGEOmfYoVJ9J2u7fxOfIMnBYJ0EEm047my6Qj5wmu00HSefhheBK1\n46XK5iBlpdSVrV28IjE8PDnWotWVyYhy9vq+LdVbrhHV3JWbRtM21AXkL/73dB3h\nBC3o+lRjmw+ySSEFlfugP+a9ULqwWtuQH+uFWq86F2Ar4y5Sl4TnIiZ9i22Yx+i4\nKcwPRPFsEyCvwRh1Ih/r/UTsrF0lqE7iQ77Yo9I9MuNKMc6y3+fI3vZWTED0QIfz\nVlb+A5Q9AfGhfaygc2fzJ9w/gnZ+D6wp/mQWQz2xNxs3iaDQf8xHpXywYNGbkVXX\ny/cTj/D8a8iAJA==\n-----END CERTIFICATE-----",
    "expiration": 1618936795,
    "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDqDCCApCgAwIBAgIUfg7l07KVEnht4ETStjHLAA3xvp4wDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjEwNDE5MTYzNTM1WhcNMjYw\nNDE4MTYzNjA1WjAtMSswKQYDVQQDEyJleGFtcGxlLmNvbSBJbnRlcm1lZGlhdGUg\nQXV0aG9yaXR5MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApranvA5f\ncP+OySUE+uKNxzR3IkWI59Z0mMYlHYBtAY47V8avXcmwsaFDJiGSq6OXJs8SXKiF\nrXONaQSudWxTO28U8AovcwoV3/C5KsldqbhLMOyor+XDWYQP7GVXGuKYhn9C+kaF\nbiyaPE0SsAb6Yl3emVl1UCq9kBbQm1XmFyih7rdREB4XJZW2Mtp5KdzlHf3zGLfB\nEcK/BF0CsC1kI5UkkJVWxLB3hKx2pr3Bl3olufQDDdweKqlg7YtiPPnmxLvuEq5n\nG5h18++mbxywIvU7iehGYDj+EBFV1zrsOmZcqfSC34xRbJLVg8wFhuQ59Zy/k+mh\nEUo63NOrT1lzTQIDAQABo4HWMIHTMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8E\nBTADAQH/MB0GA1UdDgQWBBQoQnqjxjJ8ExU3SDHRG9M67KNlLDAfBgNVHSMEGDAW\ngBSnG76ILbfk2VdLrRd6m6bVYK3qRjA8BggrBgEFBQcBAQQwMC4wLAYIKwYBBQUH\nMAKGIGh0dHBzOi8vMTI3LjAuMC4xOjgyMDAvdjEvcGtpL2NhMDIGA1UdHwQrMCkw\nJ6AloCOGIWh0dHBzOi8vMTI3LjAuMC4xOjgyMDAvdjEvcGtpL2NybDANBgkqhkiG\n9w0BAQsFAAOCAQEAegVUIb5SFR/bXo33xqjuocINJLfec22dgjgBO0lMOGp32GFB\nIp4clgfNU1Dw8yGQEoRQHEfWDjZeGdPuCYbgu/ucLW1pLrBiQqO/XgVeFQhwnJp6\nza0NLGnmaDd5k8z1+VJ79tJa0Wb2WRxWxYqu6lsqtYPAj9jD4DM73tfGR76/rCiK\nRB9DRwlr9UTm9h0cw84UpPwaX33kfiIKBeyY9/hUe3pBzGuNGuDgjOiaMph0v+9z\nwiyNCzcR0AN0y1qDVvsqABH9GJ0BpaZ48GbZTZm91Q/kg+HdNlPkgwqpY8+V8aMa\n1CyvvvJeega8q9Evg1v68MajkFFT37YI5XESCw==\n-----END CERTIFICATE-----",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAz33uJ1VfgBZ0VIFt96l8gjguMu67s0pvT+kohIq0xU/jJjbR\nxBjwRiJhhQS2K0qjKHj4jtxqJaR1ns2O93L0cxVjP2S05n46rBTbEJj+LUtW2ymu\nwZ9mXMqWyTRDa/v3dQZL/ZiCbicCNbECyNskHvCmU9xy67a+LWxBl52P7WQ965vp\nIGTbwqtBqUwEQEwpGd6lIDk9dDuXTGHvGNhhgmYrIr4inhj9UuNhC9eULKC4byLo\ntrGcLO7Guiy3ljDWDCLFkQGLE5A33xUVhMf8itWsa9B3qPU60VQbjX0ZFPF/6dS7\nN5F1AfxzBfUbFud7mQzyW1zhw0iVYZLmz6A8VwIDAQABAoIBADMwNhiuDyliYMCY\nTbDTt0vI4FzgWJ4atutX8g8AySgEVV2QGJ/wJxamVLikOOzlNOs/LNLRvb4bnIjY\n3XRef8AEfr+c8KQMcB0T6BdoJwy1kW/wEJTj5jTuJdTtd9SkDKBqNUUS4tqZ9QmZ\n6b3zki2v4Ni/gfp00uYR1vy4elFt/yjTmA0lhY4onPNPqXNWCF1LY38xNegBQZg4\nrYkSFvIOr7bl7Rk2JljWCxZZef5kEIFGdoqus5KekzW8Li9s2XVVXWEfoY/r/NI1\nHgAwHugwe3+8ve3YKLIIKJqGvYk+8Lp8rXPsf9GRZxpxx/yER4NX8+83DndBnfQO\n7G/BOwECgYEA/0ZAU6h+1cW+PxQ+CuSdbClXhKgqTN4pRwCbrGUQ3y2KGsGUzZW/\nUuO/XIN/hkx0SkKz10TvUV5o4SXh5nY7s+3OCsnc7fBx3Gv4vHCWQ4t9JNxeH6vP\nzNKjQeceVzlniyxKlW9OvVDXZU6nv27LBRH1fIYp9QRbc7yHzUQXLCcCgYEA0BTp\nD3CXELJYoV0/LFvRQqZ+P1Xo26qa9xjRMI+Owr2nNuzqcMl4dBvZWNNCpDwqrKn6\n6iiWXYhwxvvKkJe9QgE3LCvkmluGiBDpK4U2rVbB/LoBAtNgGdnxaP9t9OfhtQC3\nPjhVJvBVbk3mFWG950Ua5E1cgl6n4xtGoHgxHFECgYBaXOTieE/FnoUU0TaRJpIv\nOoc3d0vZ//5+mtGAeho51mX/yKzDBZI/Zk1UE1xuDtxPeUMuHcHVfOUFZiKMMSg7\nLh/0o7ZoJ+g2TaY0FmqqqFL5XGSZM3mQmLOf3Y9Y8wIbOud/9HHcBCTrQKeS1UZa\nmhvbI6bwi8VPt9oeqE7HmwKBgHqOVlbJsbAb2yfvi+3MhowDFAipyOTYrz0qWMuJ\nQkRg/8PR9qNHhrKcVH+ErpOc/GWGGEsibK3aVtJcKwrO1KGzpZNWpuZjUfGCRFNl\nuraNiuQXidDoPon7W7zD9Tdx+/Zn3YXAGCc/FpJJP2MIlplIknY1Om9u4ONahVau\nc/6BAoGBAIfW6PPFjXUUn3LvcswvQAahnclYIW+Ml6peerfMr5kq0TTWykrMN4nc\nLl9oGG2ifigSUo/mz2cfemExO+hgXJP+UOOKi2LkUUpV9x1fzJFHYutiIyV4mBPd\nTFPCpLJjz3T4Nn18nzGmrQiQT6ymgt4KDx6cW+xbOLTuNsNg+0ib\n-----END RSA PRIVATE KEY-----",
    "private_key_type": "rsa",
    "serial_number": "3f:03:a9:10:e0:28:df:dc:d8:a8:f9:50:7b:cd:d4:8c:01:f5:47:5e"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Select Secrets.
Select pki_int from the Secrets Engines list.
Select example-dot-com under Roles.
Enter test.example.com in the Common name field.
Expand Options and then set the TTL to 24 hours.
Click Generate. The response contains the PEM-encoded private key, key type and certificate serial number. You can click on the sensitive information toggle to show or hide the generated values.
Click Copy credentials and save it to a file.

Tip

A certificate can be renewed at any time by issuing a new certificate with the same CN. The prior certificate will remain valid through its time-to-live value unless explicitly revoked.

Step 5: Revoke certificates

If a certificate must be revoked, you can easily perform the revocation action which will cause the CRL to be regenerated. When you regenerate the CRL, Vault removes any expired certificates from it.

Note

As of Vault version 1.12.0, the PKI Secret Engine's Bring-Your-Own-Cert (BYOC) functionality allows revocation of certificates not previously stored (e.g., issued via a role with no_store=true). This means that setting no_store=true is now safe to be used globally, regardless of importance of issued certificates, and their likelihood for revocation.

In certain circumstances, you may wish to revoke an issued certificate.

To revoke a certificate, execute the following command.

$ vault write pki_int/revoke serial_number=<serial_number>

Example:

$ vault write pki_int/revoke \
    serial_number="3f:03:a9:10:e0:28:df:dc:d8:a8:f9:50:7b:cd:d4:8c:01:f5:47:5e"

Key                        Value
---                        -----
revocation_time            1655735227
revocation_time_rfc3339    2022-06-20T14:27:07.213907Z

Invoke the /pki_int/revoke endpoint to invoke a certificate using its serial number.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{"serial_number": "<serial_number>"}' \
    $VAULT_ADDR/v1/pki_int/revoke | jq

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"serial_number": "<serial_number>"}' \
   $VAULT_ADDR/v1/pki_int/revoke | jq

Step 6: Remove expired certificates

Keep the storage backend and CRL by periodically removing certificates that have expired and are past a certain buffer period beyond their expiration time.

To remove revoked certificate and clean the CRL.

$ vault write pki_int/tidy tidy_cert_store=true tidy_revoked_certs=true
WARNING! The following warnings were returned from Vault:

  * Tidy operation successfully started. Any information from the operation
  will be printed to Vault's server logs.

Note

You can expect the warning message on every invocation of the tidy command. It serves to alert the operator that they can observe progress from the tidy operation in the Vault operational log.

Invoke the /pki_int/tidy endpoint to remove revoked certificate and clean the CRL.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{"tidy_cert_store": true, "tidy_revoked_certs": true}' \
    $VAULT_ADDR/v1/pki_int/tidy | jq

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"tidy_cert_store": true, "tidy_revoked_certs": true}' \
   $VAULT_ADDR/v1/pki_int/tidy | jq

You are now finished with the steps in the main scenario, and can move to the Cleanup section from here.

The following steps 7-10 are optional and for learning about Root CA rotation; these steps also require that you are using Vault version 1.11.0 or greater.

Step 7: Rotate Root CA

Before version 1.11.0, you could not enable more than one root CA in the same PKI secrets engine mount. This makes rotating the root CA challenging when coordinating multiple PKI secrets engine mounts, and manually managing two root CAs while simultaneously deploying the new root CA to clients.

Vault version 1.11.0 introduces a set of new features in the PKI secrets engine, including multi-issuer capabilities, which include more than one root CA in the same secrets engine mount. This enables less burdensome root CA rotation. You can also use CA migration helpers to ease the operational burden of migrating a root CA controlled by Vault.

To begin learning about this functionality, enable another root CA in the existing PKI secrets engine mount using the new rotate feature.

$ vault write pki/root/rotate/internal \
    common_name="example.com" \
    issuer_name="root-2023"

Example output:

Key              Value
---              -----
certificate      -----BEGIN CERTIFICATE-----
MIIDpzCCAo+gAwIBAgIUT2afmPzCe/DQFO4c/Re0H7nC0jMwDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTQzMTA0WhcNMjIw
NzIyMTQzMTM0WjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBAMAT2ZvEAP0hzJlkVY7ZNY2sbiGpor9CAzL2Uaqd
9PtmL761XzboQHFziwDnffWdUKttZ5Gdc6KLFSPG8Bpl50PgKxwsUqr/2skLm1O/
nVPVlodr3AUkbQZ4Qc6/Fs/lhGbPglFFMXl7NVdkeOnyFUZtouXLq11A38rc6280
FzxMw16FEmwsLU/tWOwgAad7Q/Xp9l5HrlKN//+LUnaDcFmYXmNIK2CVTloUOqL3
9WPMR+CeXqGR1RkxTuJ0oy0GdLo2JMh9ndz7JQkMcU8VigJ7oqhvhxczoM/Lx0hB
8Y+wUMynn/VvbUO0uBRE1RpOpk5Zfxbb8TiYysN9PpzhVYMCAwEAAaOB7DCB6TAO
BgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUoWSv9g7d
oyvm9Xqspi9jH6kfhq8wHwYDVR0jBBgwFoAUoWSv9g7doyvm9Xqspi9jH6kfhq8w
OwYIKwYBBQUHAQEELzAtMCsGCCsGAQUFBzAChh9odHRwOi8vMTI3LjAuMC4xOjgy
MDAvdjEvcGtpL2NhMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMDEGA1UdHwQqMCgw
JqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3
DQEBCwUAA4IBAQByO9DyRVJYjK9xrnfNnD1pbG0WXWRmsk7dxtXY336ollMl0eqO
uEEHNGy0a4c1UKOjFg0LSg3c/DzUoPluUB4Kk9gs4ifn+1cm2k6G9gjT/6Wi0xIW
0t7+a7XX8ttPO7T4ZFDJT2KDINz42Oeht5u82TuKgBfdQsXm9XnJLqckQbaCZLPs
uvyAT8MrgBABOvCVF1yurHNrmu+js6fZxu4wAO7ANMBDzNPYYx0IphYRGCnBte1N
j4vSiTtlFOdf8+gdM8lSlv4XV56e10MepNSvvFDd1De6l+ErLciZJQydDklX2e3R
1GlQmm3d5Sxn5Wob3FA4nkyqLq21RlH2RRgo
-----END CERTIFICATE-----
expiration       1658500294
issuer_id        f4baa074-10d7-7fc3-1623-f6f906ceed98
issuer_name      root-2023
issuing_ca       -----BEGIN CERTIFICATE-----
MIIDpzCCAo+gAwIBAgIUT2afmPzCe/DQFO4c/Re0H7nC0jMwDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTQzMTA0WhcNMjIw
NzIyMTQzMTM0WjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBAMAT2ZvEAP0hzJlkVY7ZNY2sbiGpor9CAzL2Uaqd
9PtmL761XzboQHFziwDnffWdUKttZ5Gdc6KLFSPG8Bpl50PgKxwsUqr/2skLm1O/
nVPVlodr3AUkbQZ4Qc6/Fs/lhGbPglFFMXl7NVdkeOnyFUZtouXLq11A38rc6280
FzxMw16FEmwsLU/tWOwgAad7Q/Xp9l5HrlKN//+LUnaDcFmYXmNIK2CVTloUOqL3
9WPMR+CeXqGR1RkxTuJ0oy0GdLo2JMh9ndz7JQkMcU8VigJ7oqhvhxczoM/Lx0hB
8Y+wUMynn/VvbUO0uBRE1RpOpk5Zfxbb8TiYysN9PpzhVYMCAwEAAaOB7DCB6TAO
BgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUoWSv9g7d
oyvm9Xqspi9jH6kfhq8wHwYDVR0jBBgwFoAUoWSv9g7doyvm9Xqspi9jH6kfhq8w
OwYIKwYBBQUHAQEELzAtMCsGCCsGAQUFBzAChh9odHRwOi8vMTI3LjAuMC4xOjgy
MDAvdjEvcGtpL2NhMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMDEGA1UdHwQqMCgw
JqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3
DQEBCwUAA4IBAQByO9DyRVJYjK9xrnfNnD1pbG0WXWRmsk7dxtXY336ollMl0eqO
uEEHNGy0a4c1UKOjFg0LSg3c/DzUoPluUB4Kk9gs4ifn+1cm2k6G9gjT/6Wi0xIW
0t7+a7XX8ttPO7T4ZFDJT2KDINz42Oeht5u82TuKgBfdQsXm9XnJLqckQbaCZLPs
uvyAT8MrgBABOvCVF1yurHNrmu+js6fZxu4wAO7ANMBDzNPYYx0IphYRGCnBte1N
j4vSiTtlFOdf8+gdM8lSlv4XV56e10MepNSvvFDd1De6l+ErLciZJQydDklX2e3R
1GlQmm3d5Sxn5Wob3FA4nkyqLq21RlH2RRgo
-----END CERTIFICATE-----
key_id           775fb40a-4568-f613-2c6d-0f6802e859e1
key_name         n/a
serial_number    4f:66:9f:98:fc:c2:7b:f0:d0:14:ee:1c:fd:17:b4:1f:b9:c2:d2:33

Note that the certificate information has multi-issuer information, such as the issuer_ref and issuer_name values.

You can also list the issuers to confirm the addition of the new Root CA.
```
$ vault list pki/issuers

Keys
----
09c2c9a0-a874-36d2-de85-d79a7a51e373
f4baa074-10d7-7fc3-1623-f6f906ceed98
```
Both root CA issuers are now enabled in the same PKI secrets engine mount. While the new root CA is enabled, it's not yet actively used, and all later issuance from the mount will use the original root CA issuer, root-2022.
Tip
At this point, the new root CA certificate can be deployed to all devices which require it as part of rotating out the old root CA.
Create a role for the new example.com root CA; creating this role allows for specifying an issuer when necessary. This also provides a simple way to transition from one issuer to another by referring to it by name.
```
$ vault write pki/roles/2023-servers allow_any_name=true
Success! Data written to: pki/roles/2023-servers
```
Note
This role is only overly permissive in the names that it allows for the purposes of simplification in this tutorial.

To begin learning about the multi-issue functionality, enable another root CA in the existing PKI secrets engine mount using the new rotate feature.

Generate the new Root CA using the /pki/root/rotate/internal endpoint.

$ curl \
    --silent \
    --request PUT \
    --header "X-Vault-Request: true" \
    --header "X-Vault-Token: $(vault print token)" \
    --data '{"common_name":"example.com","issuer_name":"root-2023"}' \
    $VAULT_ADDR/v1/pki/root/rotate/internal \
    | jq

Example output:

{
  "request_id": "ddab7cc7-fc1e-9d61-853f-fbf18f064f83",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpzCCAo+gAwIBAgIUVoV/wuZMv05MacS2Pry3VrLgGhQwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTkwMTE4WhcNMjIw\nNzIyMTkwMTQ3WjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBANnVXc6+Ytvov3k68vo3HEzOKJyjdPhvGHtsk1Rh\nsIfOoMjYtCTtxOmouP2SWVE819yQP7MejfOxXjROhfX/gUvMk//ETqX6Rq+DKYjp\nq2nfAHV3KQK/hQ1VWJx37uwazwGpSfd7so8TvnxqljKZny7zC/ZKaRLbt8OqoMfn\n6xOH8IEPw0798wmg5/UTByFrf/uzN1d4tX90Batnp0fDhexK9B7YDq5CL3NaxQnI\ngxd9ry2160ng0C5w9FfqbBVSBhbGPbvweEIBvaP08S4SIoAmG6gW2gFrU/A4zAdg\nnWU1qJ+eS8D0zFZNLbCjiHyqyg3Q0lH274v/VvHW7mLBvRsCAwEAAaOB7DCB6TAO\nBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUOO/cNV1d\nogLUPuiXvryXlohDm4owHwYDVR0jBBgwFoAUOO/cNV1dogLUPuiXvryXlohDm4ow\nOwYIKwYBBQUHAQEELzAtMCsGCCsGAQUFBzAChh9odHRwOi8vMTI3LjAuMC4xOjgy\nMDAvdjEvcGtpL2NhMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMDEGA1UdHwQqMCgw\nJqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3\nDQEBCwUAA4IBAQAkvCg+Q2jLEtUE3zlEvVN8Qtb2+zz5MlHsDwKkqjZykpRjrIC7\nxTeLxHod/GbzE+7DQKWUCn8AqoFjx6X7uOKCliPZ7ndVUHtGddOfXN5/xxRi1EE3\nf4bPyxbq/4gdZFfbUuHw9ugVWIbpeWrgBJfUos47suAUyFxOkIfqKxdK5lHCO6cD\n/FExWtqlyLIyjw0v7vaoPi88SHzrEWuosSkJzOc3NcT3tLSyQg+t+sqIxfLdddqF\n6Orp6M9k1cC54h/8O8G24dq47SiqlhwGft+IZgD9NwsWfgV5r3PT96LhITNf6bLy\nXnUSjLh1FBUyuSyHTmkVTeOuxVCNPzr2BXEA\n-----END CERTIFICATE-----",
    "expiration": 1658516507,
    "issuer_id": "8247c31f-ad1e-001c-6ad9-0aacc0aebea2",
    "issuer_name": "root-2023",
    "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDpzCCAo+gAwIBAgIUVoV/wuZMv05MacS2Pry3VrLgGhQwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTkwMTE4WhcNMjIw\nNzIyMTkwMTQ3WjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBANnVXc6+Ytvov3k68vo3HEzOKJyjdPhvGHtsk1Rh\nsIfOoMjYtCTtxOmouP2SWVE819yQP7MejfOxXjROhfX/gUvMk//ETqX6Rq+DKYjp\nq2nfAHV3KQK/hQ1VWJx37uwazwGpSfd7so8TvnxqljKZny7zC/ZKaRLbt8OqoMfn\n6xOH8IEPw0798wmg5/UTByFrf/uzN1d4tX90Batnp0fDhexK9B7YDq5CL3NaxQnI\ngxd9ry2160ng0C5w9FfqbBVSBhbGPbvweEIBvaP08S4SIoAmG6gW2gFrU/A4zAdg\nnWU1qJ+eS8D0zFZNLbCjiHyqyg3Q0lH274v/VvHW7mLBvRsCAwEAAaOB7DCB6TAO\nBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUOO/cNV1d\nogLUPuiXvryXlohDm4owHwYDVR0jBBgwFoAUOO/cNV1dogLUPuiXvryXlohDm4ow\nOwYIKwYBBQUHAQEELzAtMCsGCCsGAQUFBzAChh9odHRwOi8vMTI3LjAuMC4xOjgy\nMDAvdjEvcGtpL2NhMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMDEGA1UdHwQqMCgw\nJqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3\nDQEBCwUAA4IBAQAkvCg+Q2jLEtUE3zlEvVN8Qtb2+zz5MlHsDwKkqjZykpRjrIC7\nxTeLxHod/GbzE+7DQKWUCn8AqoFjx6X7uOKCliPZ7ndVUHtGddOfXN5/xxRi1EE3\nf4bPyxbq/4gdZFfbUuHw9ugVWIbpeWrgBJfUos47suAUyFxOkIfqKxdK5lHCO6cD\n/FExWtqlyLIyjw0v7vaoPi88SHzrEWuosSkJzOc3NcT3tLSyQg+t+sqIxfLdddqF\n6Orp6M9k1cC54h/8O8G24dq47SiqlhwGft+IZgD9NwsWfgV5r3PT96LhITNf6bLy\nXnUSjLh1FBUyuSyHTmkVTeOuxVCNPzr2BXEA\n-----END CERTIFICATE-----",
    "key_id": "3e46e483-a692-3a8d-6f33-2f9173c2f110",
    "key_name": "",
    "serial_number": "56:85:7f:c2:e6:4c:bf:4e:4c:69:c4:b6:3e:bc:b7:56:b2:e0:1a:14"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Step 8: Create a cross-signed intermediate

A significant step in rotating an older root CA involves handling devices which might be offline for long periods of time, but which need to eventually come online and fetch the new root certificate.

If you want to effectively handle this situation, you can do so with the use of a cross-signed Intermediate CA between the older root to the new root, such that clients of the older root can trust certificates which the new root signs.

The new cross-sign command provides this functionality to the Vault operator in a familiar way, resembling the command syntax for creating a new intermediate CA with an existing key.

Create the cross-signed Intermediate CSR.

$ vault write -format=json pki/intermediate/cross-sign \
      common_name="example.com" \
      key_ref="$(vault read pki/issuer/root-2023 \
      | grep -i key_id | awk '{print $2}')" \
      | jq -r '.data.csr' \
      | tee cross-signed-intermediate.csr

Example output:

Sign the resulting CSR with the older root CA.

$ vault write -format=json pki/issuer/root-2022/sign-intermediate \
      common_name="example.com" \
      csr=@cross-signed-intermediate.csr \
      | jq -r '.data.certificate' | tee cross-signed-intermediate.crt

Example output:

The result is a cross-signed certificate, but no issuer gets created yet. Import the signed certificate to create the new issuer.

Import the cross-signed certificate.

$ vault write pki/intermediate/set-signed \
      certificate=@cross-signed-intermediate.crt

Example output:

Key                 Value
---                 -----
imported_issuers    [3f5a71f1-6558-0c82-2f8c-c3feb27eee8a]
imported_keys       <nil>
mapping             map[3f5a71f1-6558-0c82-2f8c-c3feb27eee8a:775fb40a-4568-f613-2c6d-0f6802e859e1]

You now have 2 root CAs with a cross-signed intermediate CA providing a trust chain between them. You are ready to handle migration of devices which were not initially possible to migrate to the new root CA.

Read the issuer for the new root CA. You'll notice that there are now more certificates in the ca_chain field.

$ vault read pki/issuer/root-2023

Example output:

Key                        Value
---                        -----
ca_chain                   [-----BEGIN CERTIFICATE-----
MIIDpzCCAo+gAwIBAgIUT2afmPzCe/DQFO4c/Re0H7nC0jMwDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTQzMTA0WhcNMjIw
NzIyMTQzMTM0WjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBAMAT2ZvEAP0hzJlkVY7ZNY2sbiGpor9CAzL2Uaqd
9PtmL761XzboQHFziwDnffWdUKttZ5Gdc6KLFSPG8Bpl50PgKxwsUqr/2skLm1O/
nVPVlodr3AUkbQZ4Qc6/Fs/lhGbPglFFMXl7NVdkeOnyFUZtouXLq11A38rc6280
FzxMw16FEmwsLU/tWOwgAad7Q/Xp9l5HrlKN//+LUnaDcFmYXmNIK2CVTloUOqL3
9WPMR+CeXqGR1RkxTuJ0oy0GdLo2JMh9ndz7JQkMcU8VigJ7oqhvhxczoM/Lx0hB
8Y+wUMynn/VvbUO0uBRE1RpOpk5Zfxbb8TiYysN9PpzhVYMCAwEAAaOB7DCB6TAO
BgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUoWSv9g7d
oyvm9Xqspi9jH6kfhq8wHwYDVR0jBBgwFoAUoWSv9g7doyvm9Xqspi9jH6kfhq8w
OwYIKwYBBQUHAQEELzAtMCsGCCsGAQUFBzAChh9odHRwOi8vMTI3LjAuMC4xOjgy
MDAvdjEvcGtpL2NhMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMDEGA1UdHwQqMCgw
JqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3
DQEBCwUAA4IBAQByO9DyRVJYjK9xrnfNnD1pbG0WXWRmsk7dxtXY336ollMl0eqO
uEEHNGy0a4c1UKOjFg0LSg3c/DzUoPluUB4Kk9gs4ifn+1cm2k6G9gjT/6Wi0xIW
0t7+a7XX8ttPO7T4ZFDJT2KDINz42Oeht5u82TuKgBfdQsXm9XnJLqckQbaCZLPs
uvyAT8MrgBABOvCVF1yurHNrmu+js6fZxu4wAO7ANMBDzNPYYx0IphYRGCnBte1N
j4vSiTtlFOdf8+gdM8lSlv4XV56e10MepNSvvFDd1De6l+ErLciZJQydDklX2e3R
1GlQmm3d5Sxn5Wob3FA4nkyqLq21RlH2RRgo
-----END CERTIFICATE-----
 -----BEGIN CERTIFICATE-----
MIIDpzCCAo+gAwIBAgIUOjMm1b+ICXC682TSMH7wsFRdYMkwDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTUwODA3WhcNMjIw
NzIyMTUwODM3WjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBAMAT2ZvEAP0hzJlkVY7ZNY2sbiGpor9CAzL2Uaqd
9PtmL761XzboQHFziwDnffWdUKttZ5Gdc6KLFSPG8Bpl50PgKxwsUqr/2skLm1O/
nVPVlodr3AUkbQZ4Qc6/Fs/lhGbPglFFMXl7NVdkeOnyFUZtouXLq11A38rc6280
FzxMw16FEmwsLU/tWOwgAad7Q/Xp9l5HrlKN//+LUnaDcFmYXmNIK2CVTloUOqL3
9WPMR+CeXqGR1RkxTuJ0oy0GdLo2JMh9ndz7JQkMcU8VigJ7oqhvhxczoM/Lx0hB
8Y+wUMynn/VvbUO0uBRE1RpOpk5Zfxbb8TiYysN9PpzhVYMCAwEAAaOB7DCB6TAO
BgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUoWSv9g7d
oyvm9Xqspi9jH6kfhq8wHwYDVR0jBBgwFoAU+RF2dgdU6BZrOKHck1QpEmqPemUw
OwYIKwYBBQUHAQEELzAtMCsGCCsGAQUFBzAChh9odHRwOi8vMTI3LjAuMC4xOjgy
MDAvdjEvcGtpL2NhMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMDEGA1UdHwQqMCgw
JqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3
DQEBCwUAA4IBAQARw49qG9j/N46En+ME8u3uK0DmVxo/Fuj/RCNOBQ3EnIJ8zU+V
hujyckHcQNQ0f8nfrdE1JHnn+bnhOIzO1qaaooSlmhWg1HuEolOn/g1Aq1xJvmOd
nWKr4G1iwo3xmID6AYAI80LaVAeRcrk+S6dmhDuo1KT4CZmGNo+sz0rguute7aTh
N568OGJF7qHoLFSn3/pe9zvpjuBiH9jiB1HmWbL/JqntTherr5JWK6W7EukGFNOd
HEn/n/QfBuKX32QU8SjVb0ZRWd7CbJwL7nsNY6jnqlwLnCOyncL8hhnW6U8QbHqd
dm1l9PpE7BssfVTk/exS/Icemf6XFzDeIrqT
-----END CERTIFICATE-----
 -----BEGIN CERTIFICATE-----
MIIDNTCCAh2gAwIBAgIUfDvqkDZG/fr7np0RZ50wHl2VO+QwDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTQyMjU1WhcNMzIw
NjE3MTQyMzI1WjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBAJkM2EYB3+5S70a+aZpJeyvN8wY1wNnRIStPnJCq
uIlgMGu3u+c/fVUwpsxh+KSGMfLnA8vdVmZhkjd+Si97RlqV4yxA6OfJYlSyrOBH
ODA3E+J302gekWPGd851EpbAx+1MDekWoGprCEaiJCVIulNAgDWSHQHqfHNKJMox
GMxvCKhse+NcVMZoRUxBPG9pgKeb7gXIXlnPVOKeZAZYzzUCrU0x/OHCD6xKOVNN
t8mmncKmUlQach8D1r0LA1IvNCYjhNF4+RGIYBAuuym2nKXI4aj3mtYrlDSnnBwZ
T3/8CdMwf0qy10KCExDHc+Yyge6EcbJBLnfYkIjOj/PzT8UCAwEAAaN7MHkwDgYD
VR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFPkRdnYHVOgW
azih3JNUKRJqj3plMB8GA1UdIwQYMBaAFPkRdnYHVOgWazih3JNUKRJqj3plMBYG
A1UdEQQPMA2CC2V4YW1wbGUuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQA+fKtmp+8j
J6KcS9aeiNgyVc2RuZQBVMkn0l9z6c6+zZwn7LbQ9LmoTfcbE8aXj3gKJlYGD+p6
6fCClmQjq8epWdT/HuO/5efFiiRsCan1eaKoK7dah9z39kfYxaXrOmG6nXjFDn0m
u+ZxBtuW3kkib0MYnVvJDe/xJ8pg2J8Mt1tAqcbDbJZWW+yEH4XFJdjDt9LxeNm7
0y2BzDfr1Ckzh/rHowHEBDX/1a2rGgdU7n5j5mgMYKCcP5G+dlWhm3kztFo2aRni
RE939WmlzLob9vgKBEkO7hfcs4kMO6TwDJx0/BZ3OpM54mgHf/DXkiY/AIsRYBp9
8iJESkjzeDAA
-----END CERTIFICATE-----
]
certificate                -----BEGIN CERTIFICATE-----
MIIDpzCCAo+gAwIBAgIUT2afmPzCe/DQFO4c/Re0H7nC0jMwDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTQzMTA0WhcNMjIw
NzIyMTQzMTM0WjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBAMAT2ZvEAP0hzJlkVY7ZNY2sbiGpor9CAzL2Uaqd
9PtmL761XzboQHFziwDnffWdUKttZ5Gdc6KLFSPG8Bpl50PgKxwsUqr/2skLm1O/
nVPVlodr3AUkbQZ4Qc6/Fs/lhGbPglFFMXl7NVdkeOnyFUZtouXLq11A38rc6280
FzxMw16FEmwsLU/tWOwgAad7Q/Xp9l5HrlKN//+LUnaDcFmYXmNIK2CVTloUOqL3
9WPMR+CeXqGR1RkxTuJ0oy0GdLo2JMh9ndz7JQkMcU8VigJ7oqhvhxczoM/Lx0hB
8Y+wUMynn/VvbUO0uBRE1RpOpk5Zfxbb8TiYysN9PpzhVYMCAwEAAaOB7DCB6TAO
BgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUoWSv9g7d
oyvm9Xqspi9jH6kfhq8wHwYDVR0jBBgwFoAUoWSv9g7doyvm9Xqspi9jH6kfhq8w
OwYIKwYBBQUHAQEELzAtMCsGCCsGAQUFBzAChh9odHRwOi8vMTI3LjAuMC4xOjgy
MDAvdjEvcGtpL2NhMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMDEGA1UdHwQqMCgw
JqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3
DQEBCwUAA4IBAQByO9DyRVJYjK9xrnfNnD1pbG0WXWRmsk7dxtXY336ollMl0eqO
uEEHNGy0a4c1UKOjFg0LSg3c/DzUoPluUB4Kk9gs4ifn+1cm2k6G9gjT/6Wi0xIW
0t7+a7XX8ttPO7T4ZFDJT2KDINz42Oeht5u82TuKgBfdQsXm9XnJLqckQbaCZLPs
uvyAT8MrgBABOvCVF1yurHNrmu+js6fZxu4wAO7ANMBDzNPYYx0IphYRGCnBte1N
j4vSiTtlFOdf8+gdM8lSlv4XV56e10MepNSvvFDd1De6l+ErLciZJQydDklX2e3R
1GlQmm3d5Sxn5Wob3FA4nkyqLq21RlH2RRgo
-----END CERTIFICATE-----
issuer_id                  f4baa074-10d7-7fc3-1623-f6f906ceed98
issuer_name                root-2023
key_id                     775fb40a-4568-f613-2c6d-0f6802e859e1
leaf_not_after_behavior    err
manual_chain               <nil>
usage                      read-only,issuing-certificates,crl-signing

Specifically, there are 3 certificates in ca_chain, as follows:

The new root CA certificate (root-2023).
The new cross-signed intermediate CA certificate.
The older root CA certificate (root-2022).

If you do not want the chain composed in this way, you can specify a custom chain with the manual_chain parameter when creating the intermediate CA. More information is available in the API documentation.

Create the cross-signed Intermediate CSR.

$ curl \
    --silent \
    --request PUT \
    --header "X-Vault-Request: true" \
    --header "X-Vault-Token: $(vault print token)" \
    --data '{"common_name":"example.com","key_ref":"3e46e483-a692-3a8d-6f33-2f9173c2f110"}' \
    http://127.0.0.1:8200/v1/pki/intermediate/cross-sign \
    | jq '.data.csr' \
    | tee cross-signed-intermediate.csr

Example output:

"-----BEGIN CERTIFICATE REQUEST-----\nMIIChDCCAWwCAQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3\nDQEBAQUAA4IBDwAwggEKAoIBAQDZ1V3OvmLb6L95OvL6NxxMziico3T4bxh7bJNU\nYbCHzqDI2LQk7cTpqLj9kllRPNfckD+zHo3zsV40ToX1/4FLzJP/xE6l+kavgymI\n6atp3wB1dykCv4UNVVicd+7sGs8BqUn3e7KPE758apYymZ8u8wv2SmkS27fDqqDH\n5+sTh/CBD8NO/fMJoOf1Ewcha3/7szdXeLV/dAWrZ6dHw4XsSvQe2A6uQi9zWsUJ\nyIMXfa8ttetJ4NAucPRX6mwVUgYWxj278HhCAb2j9PEuEiKAJhuoFtoBa1PwOMwH\nYJ1lNaifnkvA9MxWTS2wo4h8qsoN0NJR9u+L/1bx1u5iwb0bAgMBAAGgKTAnBgkq\nhkiG9w0BCQ4xGjAYMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMA0GCSqGSIb3DQEB\nCwUAA4IBAQAbWckGlLZGCYOWbbXNESvRGSbFc5+Tk6dcoOcb33r04GsfQsWTSvNh\nMmqm8ovBB2fSYxRZvZ8ciQ232XqnrKfySZ5NdTxitc52U2gWqsT64I1rwmSfvKFT\nxU23ILsAf0YSPnB1+jZ6u1Oqzj5jVsXJPB4Goyu2vCyxmwNKd8Op7FGosFoA5vl6\nji4S70L0ClR8B8Pf4i0iNbtCqPX+diMEezfgOiPv9EfCkqM+Sbh09sWHe7VTucWO\nCWiYnKYs2OKWM9S3B2shlH1rluNQe2R6UaovxAt6jlDwQYbqPmqJb3buicSdCoKI\nOZZ0VTha98YlwHrdEQwPH2brOL0ZAMi9\n-----END CERTIFICATE REQUEST-----"

Create a payload file for the intermediate information.

$ tee > payload-intermediate-csr.json << EOF
{
  "common_name": "example.com",
  "csr": $(cat cross-signed-intermediate.csr)
}
EOF

Sign the resulting CSR with the older root CA.

$ curl \
    --silent \
    --request PUT \
    --header "X-Vault-Request: true" \
    --header "X-Vault-Token: $(vault print token)" \
    --data @payload-intermediate-csr.json \
    http://127.0.0.1:8200/v1/pki/issuer/root-2022/sign-intermediate \
    | jq '.data.certificate' | tee cross-signed-intermediate.crt

Example output:

"-----BEGIN CERTIFICATE-----\nMIIDpzCCAo+gAwIBAgIUG4zofnl6wpYyuzikKXh11Oe6JHgwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTk0MTMzWhcNMjIw\nNzIyMTk0MjAzWjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBANnVXc6+Ytvov3k68vo3HEzOKJyjdPhvGHtsk1Rh\nsIfOoMjYtCTtxOmouP2SWVE819yQP7MejfOxXjROhfX/gUvMk//ETqX6Rq+DKYjp\nq2nfAHV3KQK/hQ1VWJx37uwazwGpSfd7so8TvnxqljKZny7zC/ZKaRLbt8OqoMfn\n6xOH8IEPw0798wmg5/UTByFrf/uzN1d4tX90Batnp0fDhexK9B7YDq5CL3NaxQnI\ngxd9ry2160ng0C5w9FfqbBVSBhbGPbvweEIBvaP08S4SIoAmG6gW2gFrU/A4zAdg\nnWU1qJ+eS8D0zFZNLbCjiHyqyg3Q0lH274v/VvHW7mLBvRsCAwEAAaOB7DCB6TAO\nBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUOO/cNV1d\nogLUPuiXvryXlohDm4owHwYDVR0jBBgwFoAUawEF1rPbTI4vc2/ORwjlRTR4dasw\nOwYIKwYBBQUHAQEELzAtMCsGCCsGAQUFBzAChh9odHRwOi8vMTI3LjAuMC4xOjgy\nMDAvdjEvcGtpL2NhMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMDEGA1UdHwQqMCgw\nJqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3\nDQEBCwUAA4IBAQC1peeI9oQGJUOrdknIiqg/uhQqe7yeuKwZS/Xg/ffN0Hn9Qc70\n5tgg6p3WXuGntG1EyE2l8uQ82kqzG4M9QqBMaNV3naXINdzp8ipFQfDnR0C6ekBn\nduxNgUkrVMqbUrsp7lpB1Ot+MbWXKbAY5fUVjEuXyKWBgPTEmAE/I13eZfPMLZNl\nyTjEyO3RdLZDN2SXGfvKykfN/DIazSMfV6/OhlLeiTh9mZB0ANbpmmmDu/tHVKGo\nRtjZ5J6nXxg8OJt2F0agCjz299GYWJ0Ng6sfcIqYtAmVegZc2ueVop2Sx6rIkAAa\nAmF4jUyMCxex6lnpTjIldU73BnVRVnOl2KGE\n-----END CERTIFICATE-----"

The result is a cross-signed certificate, but no issuer gets created yet. Import the signed certificate to create the new issuer.

Create a payload file.

$ cat > payload-cross-signed-cert.json << EOF
{
   "certificate": $(cat cross-signed-intermediate.crt)
}
EOF

Import the cross-signed certificate.

$ curl \
    --silent \
    --request PUT \
    --header "X-Vault-Request: true" \
    --header "X-Vault-Token: $(vault print token)" \
    --data @payload-cross-signed-cert.json \
    http://127.0.0.1:8200/v1/pki/intermediate/set-signed \
    | jq

Example output:

{
  "request_id": "ef40177c-21d0-07aa-324e-6aef145f2185",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "imported_issuers": null,
    "imported_keys": null,
    "mapping": {
      "e81a37b1-dfb7-33a3-294b-6079ea4f9b2e": "3e46e483-a692-3a8d-6f33-2f9173c2f110"
    }
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Read the issuer for the new root CA, and you'll notice that there are now more certificates in the ca_chain field.

$ curl \
    --silent \
    --header "X-Vault-Request: true" \
    --header "X-Vault-Token: $(vault print token)" \
    http://127.0.0.1:8200/v1/pki/issuer/root-2023 \
    | jq

Example output:

{
  "request_id": "1101f28b-4562-6f17-5117-e7030522e2de",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDpzCCAo+gAwIBAgIUVoV/wuZMv05MacS2Pry3VrLgGhQwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTkwMTE4WhcNMjIw\nNzIyMTkwMTQ3WjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBANnVXc6+Ytvov3k68vo3HEzOKJyjdPhvGHtsk1Rh\nsIfOoMjYtCTtxOmouP2SWVE819yQP7MejfOxXjROhfX/gUvMk//ETqX6Rq+DKYjp\nq2nfAHV3KQK/hQ1VWJx37uwazwGpSfd7so8TvnxqljKZny7zC/ZKaRLbt8OqoMfn\n6xOH8IEPw0798wmg5/UTByFrf/uzN1d4tX90Batnp0fDhexK9B7YDq5CL3NaxQnI\ngxd9ry2160ng0C5w9FfqbBVSBhbGPbvweEIBvaP08S4SIoAmG6gW2gFrU/A4zAdg\nnWU1qJ+eS8D0zFZNLbCjiHyqyg3Q0lH274v/VvHW7mLBvRsCAwEAAaOB7DCB6TAO\nBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUOO/cNV1d\nogLUPuiXvryXlohDm4owHwYDVR0jBBgwFoAUOO/cNV1dogLUPuiXvryXlohDm4ow\nOwYIKwYBBQUHAQEELzAtMCsGCCsGAQUFBzAChh9odHRwOi8vMTI3LjAuMC4xOjgy\nMDAvdjEvcGtpL2NhMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMDEGA1UdHwQqMCgw\nJqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3\nDQEBCwUAA4IBAQAkvCg+Q2jLEtUE3zlEvVN8Qtb2+zz5MlHsDwKkqjZykpRjrIC7\nxTeLxHod/GbzE+7DQKWUCn8AqoFjx6X7uOKCliPZ7ndVUHtGddOfXN5/xxRi1EE3\nf4bPyxbq/4gdZFfbUuHw9ugVWIbpeWrgBJfUos47suAUyFxOkIfqKxdK5lHCO6cD\n/FExWtqlyLIyjw0v7vaoPi88SHzrEWuosSkJzOc3NcT3tLSyQg+t+sqIxfLdddqF\n6Orp6M9k1cC54h/8O8G24dq47SiqlhwGft+IZgD9NwsWfgV5r3PT96LhITNf6bLy\nXnUSjLh1FBUyuSyHTmkVTeOuxVCNPzr2BXEA\n-----END CERTIFICATE-----\n",
      "-----BEGIN CERTIFICATE-----\nMIIDpzCCAo+gAwIBAgIUG4zofnl6wpYyuzikKXh11Oe6JHgwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTk0MTMzWhcNMjIw\nNzIyMTk0MjAzWjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBANnVXc6+Ytvov3k68vo3HEzOKJyjdPhvGHtsk1Rh\nsIfOoMjYtCTtxOmouP2SWVE819yQP7MejfOxXjROhfX/gUvMk//ETqX6Rq+DKYjp\nq2nfAHV3KQK/hQ1VWJx37uwazwGpSfd7so8TvnxqljKZny7zC/ZKaRLbt8OqoMfn\n6xOH8IEPw0798wmg5/UTByFrf/uzN1d4tX90Batnp0fDhexK9B7YDq5CL3NaxQnI\ngxd9ry2160ng0C5w9FfqbBVSBhbGPbvweEIBvaP08S4SIoAmG6gW2gFrU/A4zAdg\nnWU1qJ+eS8D0zFZNLbCjiHyqyg3Q0lH274v/VvHW7mLBvRsCAwEAAaOB7DCB6TAO\nBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUOO/cNV1d\nogLUPuiXvryXlohDm4owHwYDVR0jBBgwFoAUawEF1rPbTI4vc2/ORwjlRTR4dasw\nOwYIKwYBBQUHAQEELzAtMCsGCCsGAQUFBzAChh9odHRwOi8vMTI3LjAuMC4xOjgy\nMDAvdjEvcGtpL2NhMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMDEGA1UdHwQqMCgw\nJqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3\nDQEBCwUAA4IBAQC1peeI9oQGJUOrdknIiqg/uhQqe7yeuKwZS/Xg/ffN0Hn9Qc70\n5tgg6p3WXuGntG1EyE2l8uQ82kqzG4M9QqBMaNV3naXINdzp8ipFQfDnR0C6ekBn\nduxNgUkrVMqbUrsp7lpB1Ot+MbWXKbAY5fUVjEuXyKWBgPTEmAE/I13eZfPMLZNl\nyTjEyO3RdLZDN2SXGfvKykfN/DIazSMfV6/OhlLeiTh9mZB0ANbpmmmDu/tHVKGo\nRtjZ5J6nXxg8OJt2F0agCjz299GYWJ0Ng6sfcIqYtAmVegZc2ueVop2Sx6rIkAAa\nAmF4jUyMCxex6lnpTjIldU73BnVRVnOl2KGE\n-----END CERTIFICATE-----\n",
      "-----BEGIN CERTIFICATE-----\nMIIDNTCCAh2gAwIBAgIUa1fnttKmxiB1kV8EaWHAVqe1mrEwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTgyMDIzWhcNMzIw\nNjE3MTgyMDUyWjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBALhtn4dJrslD2s00tt9yilRCmtS3/kJWHu/wjkBF\nkCUQ4eba/PhXKHbSntD+XVV+FYZsLLOpvSxJ3htR1ebaXKFbS6VWZRmEtbfmnYoh\nyZZFC0eK+82xa/DDuJsdGa6pMaeFA7RV50LuICZoHDBzlj416HUih8v3wEqdcD16\nb7Pu1Oro3qcj/xBQ9HOQ8qTT/FyWrUgWnk/N6y7BX2fpWYH91aiNjov2QzuFTOer\n8NBJTjqbfIJK5xb9lmuKJZ2P0715UJYhAtdgJaEcOd5pzQw6Wutnh/0Z93ryQozJ\n9Q67+XgRNCDsG6CpfVIc40x7nvC0s0EUCM/hwlgf1tdEBWcCAwEAAaN7MHkwDgYD\nVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFGsBBdaz20yO\nL3NvzkcI5UU0eHWrMB8GA1UdIwQYMBaAFGsBBdaz20yOL3NvzkcI5UU0eHWrMBYG\nA1UdEQQPMA2CC2V4YW1wbGUuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCztaw07tp3\nN7oRV2eiHYnvS0r3667IWqYz0T7+epnN5YuOXSNzjgB8Zbytk2mMKDCLg5mczITi\n/naybO9dczbx2SD9FhQwR3vjy+ykcI5NLjgjQ7EZZO6tyS8ZOjK9igrcp+5XG9fw\nkmp9q64em5ZKYwhR6OP2VgUrgn6MR40BFvhRA5oXH6M+UmYebWNqBB8R2z0BTf+U\nOeO9jpsLDVuhQlis91TKJXTZS6MuZwJB5e8H5/foQXKrrprmKZf2nn95qUApwn7H\nd6y6jaa9zBu8w+HZsamZM9Qi93Vg/5XoGcuTm4XE9zcM2DKPtn79TlrElpdXEH+/\nbs7CfJ5Phq5t\n-----END CERTIFICATE-----\n"
    ],
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpzCCAo+gAwIBAgIUVoV/wuZMv05MacS2Pry3VrLgGhQwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTkwMTE4WhcNMjIw\nNzIyMTkwMTQ3WjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBANnVXc6+Ytvov3k68vo3HEzOKJyjdPhvGHtsk1Rh\nsIfOoMjYtCTtxOmouP2SWVE819yQP7MejfOxXjROhfX/gUvMk//ETqX6Rq+DKYjp\nq2nfAHV3KQK/hQ1VWJx37uwazwGpSfd7so8TvnxqljKZny7zC/ZKaRLbt8OqoMfn\n6xOH8IEPw0798wmg5/UTByFrf/uzN1d4tX90Batnp0fDhexK9B7YDq5CL3NaxQnI\ngxd9ry2160ng0C5w9FfqbBVSBhbGPbvweEIBvaP08S4SIoAmG6gW2gFrU/A4zAdg\nnWU1qJ+eS8D0zFZNLbCjiHyqyg3Q0lH274v/VvHW7mLBvRsCAwEAAaOB7DCB6TAO\nBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUOO/cNV1d\nogLUPuiXvryXlohDm4owHwYDVR0jBBgwFoAUOO/cNV1dogLUPuiXvryXlohDm4ow\nOwYIKwYBBQUHAQEELzAtMCsGCCsGAQUFBzAChh9odHRwOi8vMTI3LjAuMC4xOjgy\nMDAvdjEvcGtpL2NhMBYGA1UdEQQPMA2CC2V4YW1wbGUuY29tMDEGA1UdHwQqMCgw\nJqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3\nDQEBCwUAA4IBAQAkvCg+Q2jLEtUE3zlEvVN8Qtb2+zz5MlHsDwKkqjZykpRjrIC7\nxTeLxHod/GbzE+7DQKWUCn8AqoFjx6X7uOKCliPZ7ndVUHtGddOfXN5/xxRi1EE3\nf4bPyxbq/4gdZFfbUuHw9ugVWIbpeWrgBJfUos47suAUyFxOkIfqKxdK5lHCO6cD\n/FExWtqlyLIyjw0v7vaoPi88SHzrEWuosSkJzOc3NcT3tLSyQg+t+sqIxfLdddqF\n6Orp6M9k1cC54h/8O8G24dq47SiqlhwGft+IZgD9NwsWfgV5r3PT96LhITNf6bLy\nXnUSjLh1FBUyuSyHTmkVTeOuxVCNPzr2BXEA\n-----END CERTIFICATE-----\n",
    "issuer_id": "8247c31f-ad1e-001c-6ad9-0aacc0aebea2",
    "issuer_name": "root-2023",
    "key_id": "3e46e483-a692-3a8d-6f33-2f9173c2f110",
    "leaf_not_after_behavior": "err",
    "manual_chain": null,
    "usage": "read-only,issuing-certificates,crl-signing"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Specifically, you'll notice 3 certificates in ca_chain, as follows:

The new root CA certificate (root-2023).
The new cross-signed intermediate CA certificate.
The older root CA certificate (root-2022).

Step 9: Set default issuer

After your defined cutoff point for the older root CA, and after you have distributed the new root CA to all devices, you can switch the default issuer to the new root CA.

Use the root replace command to do this, and specify the issuer name of the new root CA as the value to the default parameter.

$ vault write pki/root/replace default=root-2023
Key        Value
---        -----
default    f4baa074-10d7-7fc3-1623-f6f906ceed98

Use the root replace command to do this, and specify the issuer name of the new root CA as the value to the default parameter.

$ curl \
    --silent \
    --request PUT \
    --header "X-Vault-Token: $(vault print token)" \
    --header "X-Vault-Request: true" \
    --data '{"default":"root-2023"}' \
    http://127.0.0.1:8200/v1/pki/root/replace \
    | jq

Example output:

{
  "request_id": "dc7459a4-7cf3-bd0d-d632-08d1554cf555",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "default": "8247c31f-ad1e-001c-6ad9-0aacc0aebea2"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

From this point forward, Vault will issue new certificates based on the new root CA (root-2023).

Step 10: Sunset defunct Root CA

The last step is to sunset the older root CA.

You can effectively sunset the older root CA by removing its ability to issue certificates, while preserving the ability to sign CRLs and revoke certificates.

Remove issuing-certificates from the Root CA capabilities.

$ vault write pki/issuer/root-2022 \
      issuer_name="root-2022" \
      usage=read-only,crl-signing | tail -n 5

Example output:

issuer_name                root-2022
key_id                     b785654a-6ab6-0904-be34-3f5b1c1e8d53
leaf_not_after_behavior    err
manual_chain               <nil>
usage                      crl-signing,read-only

You'll notice "issuing-certificates" removed from usage, and now only "crl-signing", and "read-only" are available on the older root CA. This means it cannot issue any further certificates going forward.

You can confirm this by attempting to issue a certificate directly from the older root CA.

$ vault write pki/issuer/root-2022/issue/2022-servers \
    common_name="super.secret.internal.dev" \
    ttl=10m

The request fails.

Error writing data to pki/issuer/root-2022/issue/2022-servers: Error making API request.

URL: PUT http://127.0.0.1:8200/v1/pki/issuer/root-2022/issue/2022-servers
Code: 500. Errors:

* 1 error occurred:
   * error fetching CA certificate: error while attempting to use issuer 09c2c9a0-a874-36d2-de85-d79a7a51e373: requested usage issuing-certificates for issuer [id:09c2c9a0-a874-36d2-de85-d79a7a51e373 / name:root-2022] but only had usage read-only,crl-signing

Remove issuing-certificates from the Root CA capabilities.

$ curl \
    --silent \
    --request PUT \
    --header "X-Vault-Request: true" \
    --header "X-Vault-Token: $(vault print token)" \
    --data '{"issuer_name":"root-2022","usage":"read-only,crl-signing"}' \
    http://127.0.0.1:8200/v1/pki/issuer/root-2022 \
    | jq

Example output:

{
  "request_id": "3533ed1a-b59c-6c3d-7e53-1a2a35e213c2",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDNTCCAh2gAwIBAgIUa1fnttKmxiB1kV8EaWHAVqe1mrEwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTgyMDIzWhcNMzIw\nNjE3MTgyMDUyWjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBALhtn4dJrslD2s00tt9yilRCmtS3/kJWHu/wjkBF\nkCUQ4eba/PhXKHbSntD+XVV+FYZsLLOpvSxJ3htR1ebaXKFbS6VWZRmEtbfmnYoh\nyZZFC0eK+82xa/DDuJsdGa6pMaeFA7RV50LuICZoHDBzlj416HUih8v3wEqdcD16\nb7Pu1Oro3qcj/xBQ9HOQ8qTT/FyWrUgWnk/N6y7BX2fpWYH91aiNjov2QzuFTOer\n8NBJTjqbfIJK5xb9lmuKJZ2P0715UJYhAtdgJaEcOd5pzQw6Wutnh/0Z93ryQozJ\n9Q67+XgRNCDsG6CpfVIc40x7nvC0s0EUCM/hwlgf1tdEBWcCAwEAAaN7MHkwDgYD\nVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFGsBBdaz20yO\nL3NvzkcI5UU0eHWrMB8GA1UdIwQYMBaAFGsBBdaz20yOL3NvzkcI5UU0eHWrMBYG\nA1UdEQQPMA2CC2V4YW1wbGUuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCztaw07tp3\nN7oRV2eiHYnvS0r3667IWqYz0T7+epnN5YuOXSNzjgB8Zbytk2mMKDCLg5mczITi\n/naybO9dczbx2SD9FhQwR3vjy+ykcI5NLjgjQ7EZZO6tyS8ZOjK9igrcp+5XG9fw\nkmp9q64em5ZKYwhR6OP2VgUrgn6MR40BFvhRA5oXH6M+UmYebWNqBB8R2z0BTf+U\nOeO9jpsLDVuhQlis91TKJXTZS6MuZwJB5e8H5/foQXKrrprmKZf2nn95qUApwn7H\nd6y6jaa9zBu8w+HZsamZM9Qi93Vg/5XoGcuTm4XE9zcM2DKPtn79TlrElpdXEH+/\nbs7CfJ5Phq5t\n-----END CERTIFICATE-----\n"
    ],
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDNTCCAh2gAwIBAgIUa1fnttKmxiB1kV8EaWHAVqe1mrEwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjIwNjIwMTgyMDIzWhcNMzIw\nNjE3MTgyMDUyWjAWMRQwEgYDVQQDEwtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBALhtn4dJrslD2s00tt9yilRCmtS3/kJWHu/wjkBF\nkCUQ4eba/PhXKHbSntD+XVV+FYZsLLOpvSxJ3htR1ebaXKFbS6VWZRmEtbfmnYoh\nyZZFC0eK+82xa/DDuJsdGa6pMaeFA7RV50LuICZoHDBzlj416HUih8v3wEqdcD16\nb7Pu1Oro3qcj/xBQ9HOQ8qTT/FyWrUgWnk/N6y7BX2fpWYH91aiNjov2QzuFTOer\n8NBJTjqbfIJK5xb9lmuKJZ2P0715UJYhAtdgJaEcOd5pzQw6Wutnh/0Z93ryQozJ\n9Q67+XgRNCDsG6CpfVIc40x7nvC0s0EUCM/hwlgf1tdEBWcCAwEAAaN7MHkwDgYD\nVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFGsBBdaz20yO\nL3NvzkcI5UU0eHWrMB8GA1UdIwQYMBaAFGsBBdaz20yOL3NvzkcI5UU0eHWrMBYG\nA1UdEQQPMA2CC2V4YW1wbGUuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCztaw07tp3\nN7oRV2eiHYnvS0r3667IWqYz0T7+epnN5YuOXSNzjgB8Zbytk2mMKDCLg5mczITi\n/naybO9dczbx2SD9FhQwR3vjy+ykcI5NLjgjQ7EZZO6tyS8ZOjK9igrcp+5XG9fw\nkmp9q64em5ZKYwhR6OP2VgUrgn6MR40BFvhRA5oXH6M+UmYebWNqBB8R2z0BTf+U\nOeO9jpsLDVuhQlis91TKJXTZS6MuZwJB5e8H5/foQXKrrprmKZf2nn95qUApwn7H\nd6y6jaa9zBu8w+HZsamZM9Qi93Vg/5XoGcuTm4XE9zcM2DKPtn79TlrElpdXEH+/\nbs7CfJ5Phq5t\n-----END CERTIFICATE-----\n",
    "issuer_id": "09c2c9a0-a874-36d2-de85-d79a7a51e373",
    "issuer_name": "root-2022",
    "key_id": "4616f6dc-17a4-a137-79b3-82f6b04f38d7",
    "leaf_not_after_behavior": "err",
    "manual_chain": null,
    "usage": "crl-signing,read-only"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

You'll notice "issuing-certificates" removed from usage, and now just "crl-signing", and "read-only" are available on the older root CA. This means it cannot issue any further certificates going forward.

You can confirm this by attempting to issue a certificate directly from the older root CA.

$ curl \
    --silent \
    --request PUT \
    --header "X-Vault-Request: true" \
    --header "X-Vault-Token: $(vault print token)" \
    --data '{"common_name":"super.secret.internal.dev","ttl":"10m"}' \
    http://127.0.0.1:8200/v1/pki/issuer/root-2022/issue/2022-servers \
    | jq

The request fails.

{
  "errors": [
    "1 error occurred:\n\t* error fetching CA certificate: error while attempting to use issuer 09c2c9a0-a874-36d2-de85-d79a7a51e373: requested usage issuing-certificates for issuer [id:09c2c9a0-a874-36d2-de85-d79a7a51e373 / name:root-2022] but only had usage crl-signing,read-only\n\n"
  ]
}

Certificate Revocation Lists (CRL) and Online Certificate Status Protocol (OCSP)

Both CRLs and OCSP allow interrogating revocation status of certificates.

These methods include internal security and authenticity (both CRLs and OCSP responses get signed by the issuing CA within Vault). This means both are fine to distribute over non-secure and non-authenticated channels, such as HTTP.

Vault version 1.12.0 and greater supports automated CRL rebuilding (including optional Delta CRLs which it can rebuild more often than complete CRLs) via the /config/crl API endpoint.

You can also configure automatic tidying of revoked and expired certificates with the /config/auto-tidy endpoint.

Tip

It is suggested that these features be enabled when possible to ensure compatibility with the wider PKIX ecosystem, and to enhance performance of the cluster.

Cleanup

You can unset the two environment variables, VAULT_ADDR and VAULT_TOKEN, that you set in the beginning of this tutorial and remove the files you created to clean up.

Unset the environment variables.

$ unset VAULT_ADDR VAULT_TOKEN

Remove the files.

$ rm -f \
    root_2022_ca.crt \
    intermediate.cert.pem \
    pki_intermediate.csr \
    payload.json \
    payload-url.json \
    payload-int.json \
    payload-int-cert.json \
    payload-signed.json \
    payload-role.json

If you also followed the advanced steps, you'll need to remove some additional files.

$ rm -f \
    root_2022_ca.crt \
    cross-signed-intermediate.csr \
    cross-signed-intermediate.crt

Stop the Vault server process.

$ pgrep -f vault | xargs kill

Next steps

Check out the Streamline Certificate Management with HashiCorp Vault webinar recording.

Also, refer to the Vault PKI Secrets Engine Integration tutorial for an example of Nomad using the PKI secrets engine to generate and renew the X.509 certificates it uses. To automate the process, this tutorial leverages the Consul Template tool.

Help and reference

6 tutorials

Vault 1.13 Release Highlights
The listed tutorials were updated to showcase the new enhancements introduced in Vault 1.13.
- Vault
8 tutorials

Secure Consul with Vault Integrations
Integrate with Vault to enforce security best practices.
- Consul

Personas

Challenge

Solution

Prerequisites

Policy requirements

Scenario introduction

Notice about multi-issuer functionality

Lab setup

Step 1: Generate root CA

Step 2: Generate intermediate CA

Step 3: Create a role

Step 4: Request certificates

Step 5: Revoke certificates

Step 6: Remove expired certificates

Step 7: Rotate Root CA

Step 8: Create a cross-signed intermediate

Step 9: Set default issuer

Step 10: Sunset defunct Root CA

Certificate Revocation Lists (CRL) and Online Certificate Status Protocol (OCSP)

Cleanup

Next steps

Help and reference

This tutorial also appears in: