What EAB is
ACME, defined in RFC 8555, lets a client create an account with a CA using only a key pair it generates. That is fine for a free CA such as Let’s Encrypt, which does not need to know who you are. A commercial CA does: it has to tie the ACME account to the customer, contract and products you bought.
External Account Binding, in section 7.3.4 of RFC 8555, does that. The CA gives you two values from your account with them:
- a key ID (often called the KID), which identifies your external account, and
- an HMAC key, a shared secret.
When your client registers its new ACME account, it signs the account’s public key with the HMAC key and sends that signature with the key ID. The CA checks it and links the ACME account to your customer account. A CA that requires this says so in its directory, with externalAccountRequired set to true.
What the key ID and HMAC key are not
- They are not used for every request. EAB is only needed when the account is created. After that, the client signs requests with its own account key, so the account key is the credential to protect from then on.
- They are not a certificate or a password. You cannot log in with them, but anyone holding them can create an ACME account on your contract, so treat them as secrets.
- They do not prove your domains. You still pass a DNS-01 or HTTP-01 challenge for each name, unless the CA has validated your domains in advance.
Registering in common clients
The flags below are from each client’s documentation. Replace the directory URL, key ID and HMAC key with the values from your CA.
- Certbot: pass
--server,--eab-kidand--eab-hmac-keythe first time you run it against that CA. Certbot keeps the account afterwards. See the Certbot documentation. - acme.sh: register once with
--register-account --server <directory> --eab-kid <kid> --eab-hmac-key <key>, then issue as usual against the same server. - lego: add
--eab --kid <kid> --hmac <key>with--server <directory>when you first run it. - cert-manager: set
externalAccountBindingon the ACME issuer, withkeyIDand akeySecretRefthat points to a Secret holding the HMAC key. The cert-manager documentation notes the key usually has to be base64url encoded, and that the oldkeyAlgorithmfield is deprecated.
Common EAB errors
- The HMAC key was changed on the way. HMAC keys are base64url encoded. Copying them through a tool that adds padding, line breaks or standard base64 characters breaks the signature.
- The key ID belongs to another directory. Commercial CAs often have one directory per product, for example DV and OV. EAB credentials for one do not work on another.
- The credentials were already used. Some CAs allow a key ID to bind only one ACME account. Reinstalling a client and registering again then fails, so back up the account.
- The package or contract expired. EAB credentials can stop working when the commercial agreement ends, and renewals fail with it.
Where clm.mt fits
clm.mt stores the key ID and HMAC key as secrets that are masked in the interface, registers the ACME account once per authority, and warns before an EAB package end date you enter. CA presets with EAB, such as Sectigo, are Preview: see the integrations board for what each one has been tested with. For the bigger picture, read what certificate lifecycle management is.