ACME with Certbot

ENTERPRISE This is an EJBCA Enterprise feature.

The following covers how to install and use the ACME client Certbot.

For general information on ACME (Automatic Certificate Management Environment), see ACME.

Certbot used to be Let's Encrypt's official client but is now maintained by the Electronic Frontier Foundation. It is one of the most used ACME clients, supporting issuance, renewal and revocation operations, which are all supported by EJBCA. For more information, refer to the Certbot Documentation.

Installation and Operation

Supported Versions

EJBCA Enterprise supports Certbot version 1.30.0 or higher.

The latest versions tested with EJBCA are Certbot 1.30.0 and 2.7.4 on Ubuntu 20.04.3 LTS and Certbot 2.7.4 on Oracle Linux Server 8.4.

Note: Since Certbot 2.0.0 the default key type for new certificates has changed from RSA 2048-bits to ECDSA scep256r1 (P-256).

Supported Features

The following lists supported features and limitations:

Certbot does not support EJBCA approvals for ACME account management because it does not reuse an existing account key for account registration.
Certbot does not support certificate enrollment for IP identifiers (but support is supposed to be added soon).
Certbot does not support account update or deactivation with EAB (External Account Binding). As a workaround, the EAB must be disabled temporarily to use this functionality.
Note that Certbot associates the ACME account generated with the endpoint used. This might result in unexpected behavior of Certbot if several EJBCA instances are requested from the same Certbot configuration.

Prerequisites

Super user permissions.

Super user permissions are not required if Certbot has read/write access to its working directory (usually /etc/letsencrypt, set with --work-dir) and the challenge directory of the webserver!

Installation

Using a Linux OS, use package managers such as apt (only older versions) or snap to install the current Certbot release (1.30). For more information, refer to https://certbot.eff.org/ or go to https://github.com/certbot/certbot to build Certbot from source. If you have Python 3 installed on your system, you might prefer Pythons package manager pip3 to install Certbot.

To install using apt:

$ apt-get install certbot

CODE

To install using snap:

$ snap install certbot --classic

CODE

To install using Python 3:

$ pip3 install certbot==1.30

#(leave out ==${version} to install the latest version)

CODE

Post Installation

Configure Certbot for HTTPs

Add the certificate trust chain of the EJBCA server certificate to the local trust store.

$ mkdir -p /usr/share/ca-certificates/extra

$ cp <path to Management.cacert.pem> /usr/share/ca-certificates/extra

$ update-ca-certificates

CODE

Alternatively, add no-verify-ssl = true to /etc/letsencrypt/cli.ini after installation. Otherwise, invocations of certbot-auto wrapper including --no-verifiy-ssl will fail with a “certificate verification fails” error from the python URL library, even if you imported ManagementCA.cacert.pem into ‘Certifi’ or the systems CA truststore (/usr/local/lib/python3.6/dist-packages/certifi/cacert.pem or /etc/ssl/certs/ca-certificates.crt).

$ touch /etc/letsencrypt/cli.ini
$ echo -e "no-verify-ssl = true" >> /etc/letsencrypt/cli.ini

CODE

Create Challenge Directory for Your Web Server

If you want to use the http-01 challenge validation, make sure that Certbot can write to the challenge folder of the web server, usually located in /var/www/html/.well-known/acme-challenge.

The web server must open port 80 to serve the challenge token with HTTP: http://<hostname>/.well-known/acme-challenge/<filename>.

$ mkdir -p /var/www/html/.well-known/acme-challenge

CODE

Reset Certbot

To reset certbot, move or delete all folders below /etc/letsencrypt or below the working directory specified with the --work-dir CMD option.

$ rm -rf /etc/letsencrypt/*

CODE

Show Help with Certbot -h [TOPIC]

Use the Certbot help for detailed information.

$ certbot -h [TOPIC]

CODE

Run Certbot Convenience Commands

Certbot supports single function commands like requesting the directory resource, register or deactivate an account, create a certificate order or enroll a certificate, as well as convenience commands which process an entire ACME workflow with a single CLI call.

Account Registration and Certificate Enrollment

Certbot certonly command workflow:

If no ACME account is registered already, an account key pair is generated locally by Certbot to register a new ACME account at the CA server. Otherwise Certbot tries to recover an existing account using the existing account key stored on the system.
Certbot requests the order resource of the CA server and receives the newly created order object including all authorizations and challenges required to enroll the certificate for the given identifiers.
Certbot places the challenge token in the challenge directory of the local web server.
Certbot requests the CA servers challenge resource.
The CA verifies the challenge response with the http-01 challenge.
Certbot deletes the challenge token.
Certbot generates a key pair and posts the generated CSR for the certificate to be enrolled to the CA servers finalize resource.
The CA server enrolls and stores the certificate.

Certbot downloads the certificate requesting the certificate resource received with the order object in the finalize resource response.

$ certbot certonly --no-verify-ssl --webroot -w /var/www/html --server https://localhost:8442/ejbca/acme/directory --email <e-mail-address[,e-mail-address]> --domain example.com

CODE

If cross-certificate chains for the designated CA are present in EJBCA, then the preferred-chain argument can be used to choose the intended chain. The value is the common name(CN) of the intended root CA. Note that EJBCA only supports completed cross-certificate chains ending with root CA with a self-signed certificate.
```
$ certbot certonly --no-verify-ssl --webroot -w /var/www/html --server https://localhost:8442/ejbca/acme/directory --email <e-mail-address[,e-mail-address]> --domain example.com --preferred-chain MySuperLegacyCa
```
CODE

Account Registration and Certificate Enrollment with dns-01 challenge

By default, Certbot uses the http-01 challenge validation to verify the ownership of the identifier. Use the convenience command for certificate enrollment using the dns-01 challenge.

$ certbot certonly --no-verify-ssl --manual --preferred-challenges dns certonly --server https://localhost:8442/ejbca/acme/directory --email <e-mail-address[,e-mail-address]> --domain example.com

CODE

Certbot will halt the workflow execution before challenge validation. Place the token received by Certbot as value into a DNS TXT record with name _acme-challenge.example.com and continue with certificate enrollment. Use short TTL and ensure your system receives the updated DNS entries. That is, dig example.com txt +answer +recurse should contain the challenge token.

Account Registration and Certificate Enrollment with EAB

Use the Certbot certonly command as in the previous example for Account Registration and Certificate Enrollmentt but with EAB (External Account Binding).

$ certbot certonly --no-verify-ssl --webroot -w /var/www/html --server https://localhost:8442/ejbca/acme/directory --domain example.com --eab-kid <keyIdFromCa> --eab-hmac-key <symmetrickeyFromCa>

CODE

Note that --eab-kid and --ab-hmac-key are sent by the CA to ACME account holders.

Run Certbot Commands

Account Registration

Register a new ACME account.

You can optionally register a new ACME with EAB if required, using --eab-kid <kid> and --eab-hmac-key <key>.

If an ACME account was registered with EAB, --eab-kid and --eab-hmac-key are not effective for account updates, unregistrations or certificate enrollment and do not need to be specified.

$ certbot register --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory

CODE

Account Update

Update an ACME account contact information.

$ certbot update_account --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory --email <e-mail-address[,e-mail-address]>

CODE

Account Unregistration (irreversible)

Certificates enrolled for this account are neither revoked or deleted by EJBCA.

$ certbot unregister --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory

CODE

Certificate Revocation

Revocation reasons accepted are unspecified (default), keycompromise, affiliationchanged, superseeded, or cessationofoperation.

$ certbot revoke --no-verify-ssl --reason keycompromise --server https://localhost:8442/ejbca/acme/directory --cert-path /etc/letsencrypt/live/example.com/cert.pem --no-delete-after-revoke

CODE

Certificate Renewal

Do not delete the certificate before renewal

$ certbot renew --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory --cert-name example.com --cert-path /etc/letsencrypt/live/example.com/cert.pem

CODE

Alternatively, you can repeat the certonly command to renew a certificate.

Certificate Deletion

The certificate is deleted at the client only.

$ certbot delete --no-verify-ssl --cert-name example.com --server https://localhost:8442/ejbca/acme/directory

CODE

Error Handling

Certbot Log

The Certbot log file is usually in the following location: /var/log/letsencrypt/letsencrypt.log.

You can chose additional verbose output displayed in the CLI as well.

$ certbot [SUBCOMMAND] -v [otherOptions] [-d DOMAIN1] [-d DOMAIN2]

CODE

Sometimes the EJBCA log is needed to find the root cause of a problem. For more information, see Logging.

Errors and Solutions

The following lists common errors and solutions.

CA unique subject-DN restriction

The Certbot CLI output and log file log a warning message after cleaning up the challenge tokens.

An unexpected error occurred:
The server experienced an internal error :: The server experienced an internal error

TEXT

Root cause and solution can both be found in the EJBCA server log. For more information on log levels, see Logging.

[...] INFO [org.cesecore.audit.impl.log4j.Log4jDevice] (default task-2) [...] User 'user2' is not allowed to use same subject DN as the user(s) 'user1' is/are using while issued by the same CA [...] See setting for 'Enforce unique DN' in the section Certification Authorities.

TEXT

You can disable the CAs unique subject-DN restriction or use the RA name generation schema to map your identifiers to end entities.

Unsupported private key type of ACME account

After updating Certbot or EJBCA, your ACME account key may not be recognized as valid anymore. In this case, you need to register a new ACME account. Delete the Certbots account key and configuration below /etc/letsencrypt/accounts and register a new account. Certbot will then generate a new account key.

Certbot CLI output and log file report a malformed request.

An unexpected error occurred:
The server experienced an internal error :: The server experienced an internal error

TEXT

The root cause can be found in the EJBCA server log in DEBUG mode. For more information on log levels, see Logging.

[...] DEBUG [org.ejbca.core.protocol.acme.util.AcmeJwsHelper] (default task-1) Unsupported private key type. [...] Responding to request with problem report of type urn:ietf:params:acme:error:malformed and detail 'The request message was malformed'.

TEXT

Could not update user because of Batch generation password in end entity profile setting

Certbot CLI output and log file report a malformed request while certificate enrollment.

An unexpected error occurred:
The server experienced an internal error :: Unable to process the request. Could not update user.

TEXT

The root cause can be found in the EJBCA server log in INFO mode. For more information on log levels, see Logging.

[...] WARN [org.ejbca.ui.web.protocol.acme.logic.AcmeOrderSessionBean] [...] org.ejbca.core.model.ra.raadmin.EndEntityProfileValidationException: Clearpassword (used in batch processing) cannot be used.

TEXT

Enable the Batch generation (clear text pwd storage) option in the End Entity Profile settings. For more information, see End Entity Profile Configuration in ACME.

Missing subject-DN attributes or SANs or other issues in the end entity profile settings

Certificate enrollment may fail because the end entity profile restrictions are not fulfilled, i.e. due to missing subject-DN attributes, too less DNS subject-AN or other profile restrictions.

Certbot CLI output and log file report about a malformed CSR.

An unexpected error occurred:
The CSR is unacceptable (e.g., due to a short key) :: Wrong number of DNSNAME fields in Subject Alternative Name.

TEXT

The root cause can be found in the EJBCA server log in DEBUG mode. For more information on log levels, see Logging.

[...] DEBUG [org.ejbca.ui.web.protocol.acme.logic.AcmeOrderSessionBean] (default task-1) [...] Request does not fulfill end entity profile (1430683098): Wrong number of DNSNAME fields in Subject Alternative Name.

TEXT

Change the end entity profile settings accordingly or generate your own CSR and add it to the Certbot command with --csr option.

Unsupported private key type or insufficient EKU or other issues int the certificate profile settings

Certificate enrollment may fail because the certificate profile restrictions are not fulfilled, i.e. due to a short key, insufficient EKU (needs to be Server Authentication) or other profile restrictions.

Certbot CLI output and log file report about a malformed CSR.

An unexpected error occurred:
The CSR is unacceptable (e.g., due to a short key) :: Key bit length was not one of '[8192]'.

TEXT

The root cause can be found in the EJBCA server log in INFO mode. For more information on log levels, see Logging.

[...] INFO [org.ejbca.ui.web.protocol.acme.web.AcmeProblemExceptionMapper] (default task-1) Responding to request with problem report of type urn:ietf:params:acme:error:badCSR and detail 'Key bit length was not one of '[8192]'.'

TEXT

Change the certificate profile settings accordingly or generate your own CSR and add it to the Certbot command with --csr option.