vault/website/content/docs/secrets/pki/cmpv2.mdx

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

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

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

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

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

## Enabling CMPv2 support on a Vault PKI mount

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

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

### Configuring an Issuer

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

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

### Configuring CMPv2 Authentication

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

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

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

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

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

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

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

#### Updating the PKI mount tunable parameters

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

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

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

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

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

#### Enabling CMPv2

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

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

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

## Limitations

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

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

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

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