Standard Issuance Protocols (API)

• ACME Certificate Issuance
  • ACME Directories
  • Get ACME EAB Binding Token
  • List Unused ACME EAB Binding Tokens
  • Delete Unused ACME EAB Binding Tokens
  • Get ACME Configuration
  • Set ACME Configuration
• EST - Certificate Issuance EnterpriseEnterprise
  • EST Protocol Paths EnterpriseEnterprise
  • Read EST Configuration EnterpriseEnterprise
  • Set EST Configuration EnterpriseEnterprise
• CMPv2 - Certificate Management Protocol (v2) EnterpriseEnterprise
  • CMPv2 Protocol Paths EnterpriseEnterprise
  • Read CMPv2 Configuration EnterpriseEnterprise
  • Set CMPv2 Configuration EnterpriseEnterprise

ACME certificate issuance

Starting with Vault 1.14, Vault supports the ACME certificate lifecycle management protocol for issuing and renewing leaf server certificates.

In order to use ACME, a cluster path must be set and ACME must be enabled in its configuration with the required headers enabled on the mount tuning.

Using ACME with a role requires no_store=false to be set on the role; this allows the certificate to be stored and later fetched through the ACME protocol.

ACME directories

Vault PKI supports the following ACME directories, providing different restrictions around usage (defaults, a specific issuer and/or a specific role). To interact with these directories, specify the directory URL in an ACME client. For example, with the EFF's CertBot:

$ certbot certonly --server https://localhost:8200/v1/pki/acme/directory ...

These endpoints are unauthenticated from a Vault authentication model, but internally authenticated via the ACME protocol.

When a role is not explicitly specified, behavior is specified by the default_directory_policy in the ACME configuration. These directories can also be forbidden by setting that policy as forbid. If the policy is sign-verbatim then any identifier for which the client can prove ownership of will be issued for. This is similar to using the Sign Verbatim endpoint, but with additional verification that the client has proven ownership (within the ACME protocol) of the requested certificate identifiers. When external-policy is specified as the default value, the Certificate Issuance External Policy Service (CIEPS)EnterpriseEnterprise is used for validating and templating the certificate instead of a role; ACME's challenge validation is still enforced. An optional policy name can be specified by using external-policy:policy. Roles are not used when CIEPS is used.

ACME challenge types

Vault supports the following ACME challenge types presently:

• http-01, supporting both dns and ip identifiers.
• dns-01, supporting dns identifiers including wildcards.
• tls-alpn-01, supporting only non-wildcard dns identifiers.

A custom DNS resolver used by the server for looking up DNS names for use with both mechanisms can be added via the ACME configuration.

ACME external account bindings

ACME External Account Binding (EAB) Policy can enforce that clients need to have a valid external account binding to Vault. Before registering a new account, an authenticated Vault client will need to fetch a new EAB token. This returns two values: a key identifier and an HMAC key used by the ACME client to authenticate with EAB. For example:

$ vault write -f /pki/acme/new-eab
$ certbot certonly --server https://localhost:8200/v1/pki/acme/directory \
                   --eab-kid <id> --eab-hmac-key <hmac-key>

With or without EAB, requests from the ACME client are not authenticated using traditional Vault authentication, but are instead authenticated through the ACME protocol. With EAB however, a Vault authenticated client will have to fetch an EAB token and pass it to the ACME client for use on the initial registration: this binds the ACME client's registration to an authenticated Vault endpoint, but not further to the client's entity or other information.

ACME accounts

ACME Accounts are created specific to a particular directory and are not portable across Performance Secondary clusters.

ACME required headers

ACME requires the following response headers (allowed_response_headers) to be specified by mount tuning:

• Replay-Nonce
• Link
• Location

On an existing mount, these can be specified by running the following command:

$ vault secrets tune -allowed-response-headers=Location -allowed-response-headers=Replay-Nonce \
                     -allowed-response-headers=Link \
                     pki/

Get ACME EAB binding token

This endpoint returns a new ACME binding token. The id response field can be used as the key identifier and the key response field be used as the EAB HMAC key in the ACME Client.

Each call to this endpoint will generate and return a new EAB binding token that is linked to the specific ACME directory it resides under. EAB tokens are not usable across different ACME directories.

Parameters

No parameters.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/pki/acme/new-eab

Sample response

{
  "data": {
    "created_on": "2023-05-24T14:33:00-04:00",
    "id": "bc8088d9-3816-5177-ae8e-d8393265f7dd",
    "key_type": "hs",
    "acme_directory": "acme/directory",
    "key": "MHcCAQE... additional data elided ...",
  }
}

List unused ACME EAB binding tokens

This endpoint returns a list of all unused ACME binding tokens; once used, they will be removed from this list.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/pki/eab

Sample response

{
  "data": {
    "key_info": {
      "bc8088d9-3816-5177-ae8e-d8393265f7dd": {
        "created_on": "2023-05-24T14:33:00-04:00",
        "key_type": "hs",
        "acme_directory": "acme/directory"
      }
    },
    "keys": [
      "bc8088d9-3816-5177-ae8e-d8393265f7dd"
    ]
  }
}

Delete unused ACME EAB binding tokens

This endpoint allows the deletion of an unused ACME binding token.

Parameters

• key_id (string: <required>) - The id of the EAB binding token to delete. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/pki/eab/bc8088d9-3816-5177-ae8e-d8393265f7dd

Get ACME configuration

This endpoint allows reading of the current ACME server configuration used by this mount.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/acme

Sample response

{
  "data": {
    "allowed_issuers": [
      "*"
    ],
    "allowed_roles": [
      "*"
    ],
    "default_directory_policy": "sign-verbatim",
    "dns_resolver": "",
    "eab_policy": "not-required",
    "enabled": true,
    "max_ttl": 776000
  },
}

Set ACME configuration

This endpoint allows setting the ACME server configuration used by this mount.

Parameters

• allowed_issuers (list: ["*"]) - Specifies a list issuers allowed to issue certificates via explicit ACME paths. If an allowed role specifies an issuer outside this list, it will be allowed. The default value * allows every issuer within the mount.

• allow_role_ext_key_usage (bool: false) - whether the ExtKeyUsage field from a role is used, defaults to false meaning that certificate will be signed with ServerAuth.

• allowed_roles (list: ["*"]) - Specifies a list of roles allowed to issue certificates via explicit ACME paths. The default value * allows every role within the mount to be used. If the default_directory_policy specifies a role, it must be allowed under this configuration.

• default_directory_policy (string: "sign-verbatim") - Specifies the behavior of the default ACME directory. Can be forbid, sign-verbatim or a role given by role:<role_name>. If a role is used, it must be present in allowed_roles.

• dns_resolver (string: "") - An optional overriding DNS resolver to use for challenge verification lookups. When not specified, the default system resolver will be used. This allows domains on peered networks with an accessible DNS resolver to be validated.

• eab_policy (string: "not-required") - Specified policy to enforce around External Account Bindings (EABs). The allowed values are:

  • not-required, where EABs are not enforced but are validated if specified.

  • new-account-required, where new accounts are required to have EAB but existing accounts can still be used.

  • always-required, where all accounts regardless of age are required to have EABs set.

• enabled (bool: false) - Whether ACME is enabled on this mount. When ACME is disabled, all requests to ACME directory URLs will return 404.

• max_ttl (string: "") - Specifies the maximum Time To Live provided as a string duration with time suffix. Hour is the largest suffix. If not set, defaults to the previous hard-coded behavior of 90 days (2160 hours).

Sample payload

{
    "enabled": true
}

Sample request

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

Sample response

{
  "data": {
    "allowed_issuers": [
      "*"
    ],
    "allowed_roles": [
      "*"
    ],
    "default_directory_policy": "sign-verbatim",
    "dns_resolver": "",
    "eab_policy": "not-required",
    "enabled": true
  }
}

EST Certificate issuance EnterpriseEnterprise

Within Vault Enterprise, support can be enabled for the EST (Enrollment over Secure Transport) protocol for issuing and renewing leaf certificates.

EST Protocol Paths EnterpriseEnterprise

These are the EST protocol API paths currently supported from Vault's authentication point of view. Note that the cacerts endpoint is unauthenticated.

Read EST Configuration EnterpriseEnterprise

This endpoint fetches the current EST configuration.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/est

Sample response

{
  "data": {
    "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_7fe0c1cc",
        "cert_role": "est-ca"
      },
      "userpass": {
        "accessor": "auth_userpass_2b333949"
      }
    },
    "default_mount": true,
    "default_path_policy": "sign-verbatim",
    "enable_sentinel_parsing": true,
    "enabled": true,
    "label_to_path_policy": {
      "test-label": "role:est-clients"
    },
    "last_updated": "2024-01-31T10:45:22-05:00"
  }
}

Set EST Configuration EnterpriseEnterprise

This endpoint will update EST related configuration, returning the updated values as a response along with an updated last_updated field.

Parameters

• enabled (bool: false) - Specifies whether EST is enabled or not.

• default_mount (bool: false) - Should this mount register the default .well-known/est URL path. Only a single mount can enable this across a Vault cluster

• default_path_policy (string: "") - Required to be set if default_mount is enabled. Specifies the behavior for requests using the default EST label. Can be sign-verbatim or a role given by role:<role_name>.

• label_to_path_policy (map[string]string: "") - Configures a pairing of an EST label with the redirected behavior for requests hitting that role. The path policy can be sign-verbatim or a role given by role:<role_name>. Labels must be unique across Vault cluster, and will register .well-known/est/<label> URL paths.

• authenticators (map[string]map[string]string: "") - Specifies the mount accessors EST should delegate authentication requests. Map keys can be either cert or userpass, with associated maps containing the key accessor with a value containing the auth mount's accessor. For the cert type, an optional key cert_role parameter is supported which will be passed as the name parameter during certificate authentication attempts.

• enable_sentinel_parsing (bool: false) - Parse out fields from the provided CSR making them available for Sentinel policies.

• audit_fields (list: ["common_name", "alt_names", "ip_sans", "uri_sans"]) - Fields parsed from the CSR that appear in the audit and can be used by sentinel policies. Allowed values are csr, common_name, alt_names, ip_sans, uri_sans, other_sans, signature_bits, exclude_cn_from_sans, ou, organization, country, locality, province, street_address, postal_code, serial_number, use_pss, key_type, key_bits, add_basic_constraints

Sample Payload

{
  "enabled": true,
  "default_mount": true,
  "label_to_path_policy": {
    "test-label": "role:est-clients",
    "sign-all": "sign-verbatim"
  },
  "authenticators": {
    "cert": {
      "accessor": "auth_cert_0f1df449",
      "cert_role": "cert1"
    },
    "userpass": {
      "accessor": "auth_userpass_b2b08fac"
    }
  },
  "enable_sentinel_parsing": true,
  "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"]
}

Sample request

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

Sample response

{
  "data": {
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_0f1df449",
        "cert_role": "cert1"
      },
      "userpass": {
        "accessor": "auth_userpass_b2b08fac"
      }
    },
    "default_mount": true,
    "default_path_policy": "sign-verbatim",
    "enabled": true,
    "label_to_path_policy": {
      "sign-all": "sign-verbatim",
      "test-label": "role:est-clients"
    },
    "last_updated": "2024-02-02T10:49:20-05:00"
  }
}

CMPv2 Certificate issuance EnterpriseEnterprise

Within Vault Enterprise, support can be enabled for the CMPv2 (Certificate Management Protocol) protocol for issuing and renewing leaf certificates.

CMPv2 Protocol Paths EnterpriseEnterprise

These are the CMP protocol API paths currently supported from Vault's authentication point of view.

Read CMPv2 Configuration EnterpriseEnterprise

This endpoint fetches the current CMPv2 configuration.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/cmp

Sample response

{
  "data": {
    "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
    "default_path_policy": "role:example-role",
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_7fe0c1cc",
        "cert_role": "cmp-ca"
      },
    },
    "enable_sentinel_parsing": true,
    "enabled": true,
    "last_updated": "2024-01-31T10:45:22-05:00"
  }
}

Set CMPv2 Configuration EnterpriseEnterprise

This endpoint will update CMPv2 related configuration, returning the updated values as a response along with an updated last_updated field.

Parameters

• enabled (bool: false) - Specifies whether CMPv2 is enabled or not.

• authenticators (map[string]map[string]string: "") - Specifies the mount accessors CMPv2 should delegate authentication requests. Map key can only be cert, with associated value containing the key accessor with a value containing the auth mount's accessor. An optional key cert_role parameter is supported which will be passed as the name parameter during certificate authentication attempts.

• default_path_policy (string: required): Specify the default issuance policy when the non role based cmp path is called. Must be set to either sign-verbatim (to issue via the sign-verbatim function) or role: followed by the name of a configured role.

• enable_sentinel_parsing (bool: false) - Parse out fields from the provided CSR making them available for Sentinel policies.

• audit_fields (list: ["common_name", "alt_names", "ip_sans", "uri_sans"]) - Fields parsed from the CSR that appear in the audit and can be used by sentinel policies. Allowed values are csr, common_name, alt_names, ip_sans, uri_sans, other_sans, signature_bits, exclude_cn_from_sans, ou, organization, country, locality, province, street_address, postal_code, serial_number, use_pss, key_type, key_bits, add_basic_constraints

Sample Payload

{
  "enabled": true,
  "authenticators": {
    "cert": {
      "accessor": "auth_cert_0f1df449",
      "cert_role": "cert1"
    },
   "default_path_policy": "sign-verbatim",
   "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
   "enable_sentinel_parsing": true
  }
}

Sample request

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

Sample response

{
  "data": {
    "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_0f1df449",
        "cert_role": "cert1"
      },
    "default_path_policy": "sign-verbatim",
    "enabled": true,
    "enable_sentinel_parsing": true,
    "last_updated": "2024-02-02T10:49:20-05:00"
  }
}