ACME EAB—What Is It, and How Do We Use It at Smallstep?
Linda Ikechukwu
External Account Binding (EAB) adds more security and control to the process of automating certificate management actions for machines and services using the ACME protocol.
Before adding the EAB feature, we’ve always advised our users against setting up ACME provisioners directly on their hosted Smallstep Certificate Manager Authority. This is because ACME provisioners are publicly accessible, and any foreign entity privy to your ACME provisioner URL can use it to obtain certificates. Depending on the provisioner or authority policy in place, such entity merely has to prove that they control the domain or IP address specified in the certificate request. So if there’s no policy in place, it can be any domain.
While such an occurrence may be far-fetched, an unprotected ACME provisioner introduces the possibility of unauthorized access, and we can all agree that the possibility of unauthorized access is never good news. A certificate obtained from your CA can be used to access other systems configured to trust certificates chained to your CA root. Alternatively, an attacker could generate a large number of requests for numerous bogus domains, leading to a (D)DoS.
We’ve long promoted using an ACME RA on the local network configured with an upstream CA as a workaround to curb unauthorized access to ACME provisioners. That way, only systems on your local network could get a certificate. However, for scenarios where systems outside your local network need to obtain certificates from your CA, the ACME RA workaround will not cut it. And that’s where ACME EAB comes in.
What is ACME External Account Binding (EAB)?
The ACME protocol (RFC 8555) defines EAB as a functionality that allows an ACME account to be associated with some notion of an account that you already know, such as in a CRM or configuration management solution. EAB adds a layer of protection over your ACME provisioners on a hosted CA, and prevents any random ACME client from using your ACME provisioners to obtain certificates from your CA.
If you configure your ACME provisioner to require EAB, only ACME clients that have been preconfigured with valid EAB credentials will be able to create an account with that ACME provisioner and therefore obtain certificates. When the CA receives a certificate request from an ACME client, it will check its records to confirm that an EAB key exists for the client and the key has been bound to the ACME account requesting the certificate. The CA declines the request if the ACME client does not meet said requirements.
How to enable EAB on the Smallstep Certificate Manager platform
1. Create an ACME provisioner and mandate it to require EAB credentials.
On the Smallstep platform, EAB credentials are managed per ACME provisioner. You can configure an ACME provisioner to require EAB on step CLI using the command:
step ca provisioner add my-acme-provisioner-name --type -ACME --require-eab
Alternatively, if you’re not comfortable with the command line, you’ll soon be able to do the same on the Smallstep Certificate Manager GUI:
2. Create an EAB credential on your ACME provisioner
Every EAB credential you create will consist of two values: A *key ID* (an ASCII string) and the actual key: an *HMAC key* (in base64url-encoded form).
To generate these credentials, you can run the following command on the CLI:
step ca acme eab add my-acme-provisioner-name
See our acme eab subcommand documentation for more options.
Alternatively, you’ll soon be able to do the same on the GUI:
Notes:
- EABs belong to specific provisioners. Therefore, an EAB key created for provisioner X can’t be used with provisioner Y.
- EAB credentials are shown only once (at the time of creation). So, remember to copy them out as soon as they’re generated. Also, you cannot recover lost EAB credentials. If you lose access to your credentials, you must regenerate them.
3. Bind EAB credentials to your ACME client
The process for doing this depends on the ACME client. Usually, it’ll involve adding the EAB *key ID* and *HMAC key* to the ACME client’s configuration file.
If you use ACME clients that support EAB, a quick search for ‘eab’ on their docs should bring up reference docs on how to use your newly created EAB credentials with your ACME client. Here are links containing information on how to bind your EAB credentials to some popular ACME clients:
Notes:
- An EAB credential can only be used once by an ACME client. Once an ACME client successfully registers an ACME account using an EAB credential, the EAB credential is marked as bound by the CA and cannot be reused. The ACME client should securely store the ACME account key, because that’s required when requesting a new certificate.
- Our open source step ca certificate authority offering does not support EAB. EAB is for more advanced ACME use cases, and is only supported in our commercial offering.
- There is currently no way to bind a step CLI ACME client to an EAB credential. However, you can use the step CLI to create, list, and delete EAB credentials.
Need even more control over your ACME provisioner?
We also offer provisioner-level and ACME Account level policy features, if you need more granular control over your ACME provisioners. In addition to limiting which ACME clients can request certificates using your ACME provisioner, you can also limit the types of certificates and entities for which they can request certificates. These features are not available on open-source, so sign up for a free hosted Smallstep Certificate Manager authority to try them out.
About the author: Linda is an educator at heart, and her superpower is demystifying complexity. Since joining SmallStep as a developer advocate, her new mission is now to demystify and educate about PKI and digital certificates :)
