PKI secrets engine - Certificate Management Protocol v2 (CMPv2)

This document summarizes Vault's PKI Secrets Engine implementation of the CMPv2 protocol Enterprise, its configuration, and limitations.

What is Certificate Management Protocol v2 (CMPv2)?

The CMP protocol is an IETF standardized protocol, RFC 4210, that allows clients to acquire client certificates and their associated Certificate Authority (CA) certficates.

Enabling CMPv2 support on a Vault PKI mount

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

Configuring an Issuer

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

See Generate intermediate CSR

Configuring CMPv2 Authentication

At this time, Vault's implementation of CMPv2 supports only Certificate TLS authentication, where clients proof of posession of a TLS client certificate authenticates them to Vault.

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

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

When setting up the authentication mount for CMPv2 clients, the token type must be configured to return batch tokens. Batch tokens are required to avoid an excessive amount of leases being generated and persisted as every CMPv2 incoming request needs to be authenticated.

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

If using the sign-verbatim as a path policy, the following ACL policy will allow an authenticated client access the required PKI CMP path.

path “pki/cmp” {
  capabilities=[“update”, “create”]
}

For a role base path policy, this sample policy can be used

path “pki/roles/my-role-name/cmp” {
  capabilities=[“update”, “create”]
}

Updating the PKI mount tunable parameters

Once the authentication mount has been created and configured, the authentication mount's accessor will need to be captured and added within the PKI mount's delegated auth accessors.

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

$ vault read -field=accessor sys/auth/auth/cert

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

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

Enabling CMPv2

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

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

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

Limitations

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

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

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

Certificate Metadata - CMPv2 has no means of providing metadata.
Certificate Issuance External Policy Service (CIEPS)