Yoko fee3c2072d

[Guide] Build Your Own CA Guide (#4995 )

* WIP

* WIP

* WIP - Jake's PKI demo

* WIP

* PKI secret engine guide

* Added little more description about role

* Added tidy step

* Fixed a broken link

2018-08-06 14:42:46 -07:00

21 KiB

Raw Blame History

layout	page_title	sidebar_current	description
guides	Build Your Own Certificate Authority - Guides	guides-secret-mgmt-pki	The PKI secrets engine generates dynamic X.509 certificates. With this secrets engine, services can get certificates without going through the usual manual process of generating a private key and CSR, submitting to a CA, and waiting for a verification and signing process to complete. Vault's built-in authentication and authorization mechanisms provide the verification functionality.

Build Your Own Certificate Authority (CA)

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

Reference Material

Estimated Time to Complete

15 minutes

Personas

The steps described in this guide are typically performed by 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 X509 certificates for usage in MTLS or other arbitrary PKI encryption. While this can be used to create web server certificates. If users do not import the CA chains, the browser will complain about 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 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 the Vault (air gapped)
Create CSRs for the intermediates
Sign CSR outside Vault and import intermediate
Issue leaf certificates from the Intermediate CA

Prerequisites

To perform the tasks described in this guide, you need to have a Vault environment. Refer to the Getting Started guide to install Vault.

Alternatively, you can use the Vault Playground environment.

Policy requirements

-> NOTE: For the purpose of this guide, you can use 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 guide, your policy must include the following permissions:

# 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 guide.

Steps

In this guide, you are going to first generate a self-signed root certificate. Then you are going to generate an intermediate certificate which is signed by the root. Finally, you are going to generate a certificate for test.example.com domain.

In this guide, you perform the following:

Generate Root CA
Generate Intermediate CA
Create a Role
Request Certificates
Revoke Certificates
Remove Expired Certificates

Step 1: Generate Root CA

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

CLI command

First, enable the pki secrets engine at pki path:
```
$ vault secrets enable 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
```
Generate the root certificate and save the certificate in CA_cert.crt.
```
$ vault write -field=certificate pki/root/generate/internal common_name="example.com" \
        ttl=87600h > CA_cert.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).

Configure the CA and CRL URLs:

$ 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"

API call using cURL

First, enable the pki secrets engine at pki path using /sys/mounts endpoint:

$ curl --header "X-Vault-Token: <TOKEN>" \
       --request POST \
       --data <PARAMETERS> \
       <VAULT_ADDRESS>/v1/sys/mounts/<PATH>

Where <TOKEN> is your valid token, and <PARAMETERS> holds configuration parameters of the secret engine.

Example:

The following example mounts pki secret engine.

$ curl --header "X-Vault-Token: ..." \
       --request POST \
       --data '{"type":"pki"}' \
       https://127.0.0.1:8200/v1/sys/mounts/pki

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

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

Generate the root certificate and extract the CA certificate and save it as CA_cert.crt.

NOTE: The following command uses jq tool to parse the output JSON. You can install jq or manually copy and paste the certificate in a file, CA_cert.crt.
```
$ tee payload.json <<EOF
{
  "common_name": "example.com",
  "ttl": "87600h"
}
EOF

$ curl --header "X-Vault-Token: ..." \
       --request POST \
       --data @payload.json \
       https://127.0.0.1:8200/v1/pki/root/generate/internal \
       | jq -r ".data.certificate" > CA_cert.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).

Configure the CA and CRL URLs:

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

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

Web UI

Open a web browser and launch the Vault UI (e.g. http://127.0.0.1:8200/ui) and then login.

Select Enable new engine.
Select PKI from the Secrets engine type drop-down list.
Click More options to expand and set the Maximum lease TTL to 87600 hours.
Click Enable Engine.
Select Configure.
Click Configure CA.
Leave CA Type as root, and Type to be internal. Enter example.com in the Common Name field.
Select Options and then set TTL field to be 87600 hours.
Click Save.
Click Copy Certificate and save it in a file named, CA_cert.crt.
Click the URLs tab, and then set:
- Issuing certificates: http://127.0.0.1:8200/v1/pki/ca
- CRL Distribution Points: http://127.0.0.1:8200/v1/pki/crl
Click Save.

-> NOTE: To examine the generated root certificate, you can use OpenSSL.

# Print the certificate in text form
$ openssl x509 -in CA_cert.crt -text

# Print the validity dates
$ openssl x509 -in CA_cert.crt -noout -dates

Step 2: Generate Intermediate CA

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

CLI Command

First, enable the pki secrets engine at pki_int path:
```
$ vault secrets enable -path=pki_int pki
```
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
```

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" ttl="43800h" \
        | jq -r '.data.csr' > pki_intermediate.csr

Sign the intermediate certificate with the root certificate and save the generated certificate as intermediate.cert.pem:

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

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

API call using cURL

First, enable the pki secrets engine at pki_int path:

Example:

$ curl --header "X-Vault-Token: ..." \
       --request POST \
       --data '{"type":"pki"}' \
       https://127.0.0.1:8200/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: ..." \
       --request POST \
       --data '{"max_lease_ttl":"43800h"}' \
       https://127.0.0.1:8200/v1/sys/mounts/pki_int/tune

Generate an intermediate using the /pki_int/intermediate/generate/internal endpoint.

$ tee payload-int.json <<EOF
{
  "common_name": "example.com Intermediate Authority",
  "ttl": "43800h"
}
EOF

$ curl --header "X-Vault-Token: ..." \
       --request POST \
       --data @payload-int.json \
       https://127.0.0.1:8200/v1/pki_int/intermediate/generate/internal | jq

Copy the generated CSR.

Sign the intermediate certificate with the root certificate and save the certificate as intermediate.cert.pem.

-> NOTE: The API request payload should contain the CSR you obtained.
```
$ tee payload-int-cert.json <<EOF
{
  "csr": "...",
  "format": "pem_bundle"
}
EOF

$ curl --header "X-Vault-Token: ..." \
       --request POST \
       --data @payload-int-cert.json \
       https://127.0.0.1:8200/v1/pki/root/sign-intermediate | jq
```
NOTE: The format in the payload specifies the format of the returned data. When pem_bundle, the certificate field will contain the certificate.

Copy the generated 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.

-> NOTE: The API request payload should contain the certificate you obtained.

$ tee payload-signed.json <<EOF
{
  "certificate": "..."
}
EOF

$ curl --header "X-Vault-Token: ..." \
       --request POST \
       --data @payload-signed.json \
       https://127.0.0.1:8200/v1/pki_int/intermediate/set-signed

Web UI

Select Enable new engine in the Secrets tab.
Select PKI from the Secrets engine type drop-down list.
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 Configure.
Click Configure CA.
Select intermediate from CA Type drop-down list.
Enter example.com Intermediate Authority in the Common Name field, and then click Save.
Click Copy CSR and save it in a file, pki_intermediate.csr.
Select pki from the Secrets tab to return to the root CA.
Select Configure and then click Sign intermediate.
Paste in the CSR in 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 Cooy 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 Configure and then 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 usages that they are valid for, and more.

Calling out some of the parameters:

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.

CLI Command

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

$ vault write pki_int/roles/example-dot-com \
        allowed_domains="example.com" \
        allow_subdomains=true \
        max_ttl="720h"

API call using cURL

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

$ tee payload-role.json <<EOF
{
  "allowed_domains": "example.com",
  "allow_subdomains": true,
  "max_ttl": "720h"
}

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

Web UI

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

Click pki_int and then select Create role.
Enter example-dot-com in the Role name field.
Select Options to expand, and then set the Max TTL to 43800 hours. Select Hide Options.
Select Domain Handling to expand, 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 to be short to align with Vault's philosophy of short-lived secrets.

CLI Command

Execute the following command to request a new certificate for 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.

API call using cURL

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

Example:

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

$ curl --header "X-Vault-Token: ..." \
       --request POST \
       --data '{"common_name": "test.example.com", "ttl": "24h"}' \
       https://127.0.0.1:8200/v1/pki_int/issue/example-dot-com | jq
{
 "request_id": "6fa8d77d-0758-33ae-b5ea-8b3d15014fd1",
 "lease_id": "",
 "renewable": false,
 "lease_duration": 0,
 "data": {
   "certificate": "-----BEGIN CERTIFICATE-----\nMIIDvzCCAqegAwIBAgIUG7H0Pzpqm+...-----END CERTIFICATE-----",
   "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDNTCCAh2gAwIBAgIUQhIX9D...-----END CERTIFICATE-----",
   "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAr6IsROOW5...-----END RSA PRIVATE KEY-----",
   "private_key_type": "rsa",
   "serial_number": "1b:b1:f4:3f:3a:6a:9b:e8:33:af:f7:1b:b1:4d:57:7f:65:65:39:c1"
 },
 "wrap_info": null,
 "warnings": null,
 "auth": null
}

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

Web UI

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.
Select Options to expand, and then set the TTL to 24 hours.
Select Hide Options and then click Generate.

The response contains the PEM-encoded private key, key type and certificate serial number.
Click Copy credentials and save it in a file.

-> NOTE: A certificate can be rotated at any time by simply issuing a new certificate with the same CN.

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 the CRL is regenerated, any expired certificates are removed from the CRL.

CLI Command

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

To revoke:

$ vault write pki_int/revoke serial_number=<serial_number>

Example:

$ vault write pki_int/revoke serial_number="48:97:82:dd:f0:d3:d9:7e:53:25:ba:fd:f6:77:3e:89:e5:65:cc:e7"
Key                        Value
---                        -----
revocation_time            1532539632
revocation_time_rfc3339    2018-07-25T17:27:12.165206399Z

API call using cURL

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

Example:

$ curl --header "X-Vault-Token: ..." \
       --request POST \
       --data '{"serial_number": "48:97:82:dd:f0:d3:d9:7e:53:25:ba:fd:f6:77:3e:89:e5:65:cc:e7"}' \
       https://127.0.0.1:8200/v1/pki_int/revoke

Web UI

Select Secrets.
Select pki_int from the Secrets Engines list.
Select the eCertificates tab.
Select the serial number for the certificate you wish to revoke.
Click Revoke. At the confirmation, click Revoke again.

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.

CLI Command

To remove revoked certificate and clean the CRL.

$ vault write pki_int/tidy tidy_cert_store=true tidy_revocation_list=true

API call using cURL

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

Example:

$ curl --header "X-Vault-Token: ..." \
       --request POST \
       --data '{"tidy_cert_store": true, "tidy_revocation_list": true}' \
       https://127.0.0.1:8200/v1/pki_int/tidy

Web UI

Select Secrets.
Select pki_int from the Secrets Engines list.
Select Configure.
Select the Tidy tab.
Select the check-box for Tidy the Certificate Store and Tidy the Revocation List (CRL).
Click Save.

Next steps

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

21 KiB Raw Blame History

Build Your Own Certificate Authority (CA)

Reference Material

Estimated Time to Complete

Personas

Challenge

Solution

Prerequisites

Policy requirements

Steps

Step 1: Generate Root CA

CLI command

API call using cURL

Web UI

Step 2: Generate Intermediate CA

CLI Command

API call using cURL

Web UI

Step 3: Create a Role

CLI Command

API call using cURL

Web UI

Step 4: Request Certificates

CLI Command

API call using cURL

Web UI

Step 5: Revoke Certificates

CLI Command

API call using cURL

Web UI

Step 6: Remove Expired Certificates

CLI Command

API call using cURL

Web UI

Next steps

21 KiB

Raw Blame History