Skip to main content

PKI secrets engine - setup and usage

This document provides a brief overview of the setup and usage of the PKI Secrets Engine.

Setup​

Most secrets engines must be configured in advance before they can perform their functions. These steps are usually completed by an operator or configuration management tool.

  1. Enable the PKI secrets engine:

    $ bao secrets enable pki
    Success! Enabled the pki secrets engine at: pki/

    By default, the secrets engine will mount at the name of the engine. To enable the secrets engine at a different path, use the -path argument.

  2. Increase the TTL by tuning the secrets engine. The default value of 30 days may be too short, so increase it to 1 year:

    $ bao secrets tune -max-lease-ttl=8760h pki
    Success! Tuned the secrets engine at: pki/

    Note that individual roles can restrict this value to be shorter on a per-certificate basis. This just configures the global maximum for this secrets engine.

  3. Configure a CA certificate and private key. OpenBao can accept an existing key pair, or it can generate its own self-signed root. In general, we recommend maintaining your root CA outside of OpenBao and providing OpenBao a signed intermediate CA.

    $ bao write pki/root/generate/internal \
        common_name=my-website.com \
        ttl=8760h

    Key              Value
    ---              -----
    certificate      -----BEGIN CERTIFICATE-----...
    expiration       1536807433
    issuing_ca       -----BEGIN CERTIFICATE-----...
    serial_number    7c:f1:fb:2c:6e:4d:99:0e:82:1b:08:0a:81:ed:61:3e:1d:fa:f5:29

    The returned certificate is purely informative. The private key is safely stored internally in OpenBao.

  4. Update the CRL location and issuing certificates. These values can be updated in the future.

    $ bao write pki/config/urls \
        issuing_certificates="http://127.0.0.1:8200/v1/pki/ca" \
        crl_distribution_points="http://127.0.0.1:8200/v1/pki/crl"
    Success! Data written to: pki/config/urls

  5. Configure a role that maps a name in OpenBao to a procedure for generating a certificate. When users or machines generate credentials, they are generated against this role:

    $ bao write pki/roles/example-dot-com \
        allowed_domains=my-website.com \
        allow_subdomains=true \
        max_ttl=72h
    Success! Data written to: pki/roles/example-dot-com

Usage​

After the secrets engine is configured and a user/machine has an OpenBao token with the proper permission, it can generate credentials.

  1. Generate a new credential by writing to the /issue endpoint with the name of the role:

    $ bao write pki/issue/example-dot-com \
        common_name=www.my-website.com

    Key                 Value
    ---                 -----
    certificate         -----BEGIN CERTIFICATE-----...
    issuing_ca          -----BEGIN CERTIFICATE-----...
    private_key         -----BEGIN RSA PRIVATE KEY-----...
    private_key_type    rsa
    serial_number       1d:2e:c6:06:45:18:60:0e:23:d6:c5:17:43:c0:fe:46:ed:d1:50:be

    The output will include a dynamically generated private key and certificate which corresponds to the given role and expires in 72h (as dictated by our role definition). The issuing CA and trust chain is also returned for automation simplicity.

API​

The PKI secrets engine has a full HTTP API. Please see the PKI secrets engine API for more details.