PKI secrets engine - Enrollment over Secure Transport (EST)

This document covers configuration and limitations of Vault's PKI Secrets Engine implementation of the EST protocol Enterprise.

What is Enrollment over Secure Transport (EST)?

The EST protocol is an IETF standardized protocol, RFC 7030, that allows clients to acquire client certificates and associated Certificate Authority (CA) certificates.

Enabling EST support on a Vault PKI mount

The following is a list of steps required to configure an existing PKI mount to serve EST clients. Each of which can be broken down within three main categories.

Configuring EST Authentication

The EST protocol specifies a few different authentication mechanisms, of which Vault supports two.

Both of these authentication mechanisms leverage a separate Vault authentication mount, within the same namespace, to validate the client provided credentials along with the client's ACL policy to enforce. While both authentication schemes can be enabled at once, only a single mount will be used to authenticate a client based on the way credentials were provided through EST. If an EST client sends HTTP-Based authentication credentials, they will be preferred over TLS client certificates.

For proper accounting, mounts supporting EST authentication should be dedicated to this purpose, not shared with other workflows. In other words, create a new auth mount for EST even if you already have one of the same type for other purposes.

When setting up the authentication mount for EST 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 EST incoming request needs to be authenticated.

The path within an ACL policy, must match the internal redirected path including the mount and not the .well-known/est/ URI the client is initially using. The path to use within the plugin depends on the path policy that is in configured for the EST label being used by the client.

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

path “pki/est/simpleenroll” {
  capabilities=[“update”, “create”]
}
path “pki/est/simplereenroll” {
  capabilities=[“update”, “create”]
}

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

path “pki/roles/my-role-name/est/simpleenroll” {
  capabilities=[“update”, “create”]
}
path “pki/roles/my-role-name/est/simplereenroll” {
  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/userpass

For EST to work within certain clients, a few response headers need to be explicitly allowed along with configuring the list of accessors the mount can delegate authentication towards. 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_userpass_e2f4f6d5" \
  -delegated-auth-accessors="auth_cert_4088ac2d" \
  pki

PKI EST configuration

The EST protocol specifies that an EST server must support a URI path-prefix of .well-known/est/ as defined in RFC-5785. EST client's normally don't provide any sort of configuration for different path-prefixes, and will default to hitting the host on the path https://<hostname>:<port>/.well-known/est/.

Some clients allow a single label, sometimes referred to as additional path segment, to accommodate different issuers. This label will be added to the path after the est path such as https://<hostname>:<port>/.well-known/est/<label>/.

To provide different restrictions around usage (defaults, an issuer or role), for EST protocol endpoints, a path policy is associated with the EST label.

Path	Default Policy Path	Issuer	Role
`/pki/est/{cacerts, simpleenroll, simplereenroll}`	`sign-verbatim`	`default`	Sign-Verbatim
`/pki/est/{cacerts, simpleenroll, simplereenroll}`	`role:role_ref`	Specified by the role	`:role_ref`
`/pki/roles/:role/est/{cacerts, simpleenroll, simplereenroll}`	(any)	Specified by the role	`:role`

Within the Vault EST configuration API, a PKI mount can be specified as the default mount by enabling default_mount to true, or provide a mapping of a label within label_to_path_policy

As an example of a complete EST configuration, that would enable the pki mount to register the .well-known/est default label, along with two additional labels of test-label and sign-all.

The test-label would use the existing est-clients PKI role for restrictions and defaults, leveraging the issuer specified within the role. The other two labels, default and sign-all will leverage a sign-verbatim type role, allowing any identifier to be issued using the default issuer.

vault write pki/config/est -<<EOC
{
  "enabled": true,
  "default_mount": true,
  "default_path_policy": "sign-verbatim",
  "label_to_path_policy": {
    "test-label": "role:est-clients",
    "sign-all": "sign-verbatim"
  },
  "authenticators": {
    "cert": {
      "accessor": "auth_cert_4088ac2d"
    },
    "userpass": {
      "accessor": "auth_userpass_e2f4f6d5"
    }
  }
}
EOC

Limitations

EST API Support

The initial implementation covers solely the required API endpoints of the EST protocol. The following optional features from the specification are not currently supported.

Well Known redirections

The EST configuration parameters default_mount and/or label_to_path_policy can be used to register paths within the .well-known path space. The following limitations apply:

Only a single PKI mount, across all namespaces, can be enabled as the default_mount.
Labels within label_to_path_policy must also be unique across all PKI mounts regardless of namespace.
Care must be taken if enabling EST on a local PKI mount on performance secondary clusters. Vault cannot guarantee the configured EST labels do not conflict across different PKI mounts in this use-case. This can lead to different issuers being used across clusters for the same EST labels.

API

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