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.20.0 or higher.

    The latest version tested with EJBCA is Certbot 1.29.0 on Ubuntu 20.04.3 LTS.

    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.18). 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

    To install using snap:

    $ snap install certbot --classic

    To install using Python 3:

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

    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

    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).

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

    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

    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/*

    Show Help with Certbot -h [TOPIC]

    Use the Certbot help for detailed information.

    $ certbot -h [TOPIC]

    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:

    1. 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.

    2. 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.

    3. Certbot places the challenge token in the challenge directory of the local web server.

    4. Certbot requests the CA servers challenge resource.

    5. The CA verifies the challenge response with the http-01 challenge.

    6. Certbot deletes the challenge token.

    7. Certbot generates a key pair and posts the generated CSR for the certificate to be enrolled to the CA servers finalize resource.

    8. The CA server enrolls and stores the certificate.

    9. 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

    10. If cross certificate chains for the designated CA is present in EJBCA then preferred-chain argument may be used to choose the intended chain. The value is common name(CN) of the intended root CA. Note that EJBCA only supports completed cross certificate chains ending with root CA with 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

    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

    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>

    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>.

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

    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]>

    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

    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

    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

    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

    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]

    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

    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.

    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

    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'.

    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.

    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.

    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.

    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.

    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]'.

    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]'.'

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