ACME with acme.sh

ENTERPRISE This is an EJBCA Enterprise feature.

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

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

Acme.sh is an ACME protocol client written in Shell (Unix shell) language, compatible with bash, dash, and sh shells. For more information, refer to acme.sh on GitHub.

Installation and Operation

Supported Versions

EJBCA Enterprise supports acme.sh version 3.0.0.

The latest version tested with EJBCA Enterprise is acme.sh 3.0.0.

Note that since EJBCA´s challenge validation is synchronous, you have to use an adapted version of the acme.sh script.

Download

Download or install acme.sh from the GitHub repository https://github.com/acmesh-official/acme.sh.

Supported Features

The following highlights supported features:

  • acme.sh supports EJBCA approvals for ACME account management.

  • acme.sh supports certificate enrollment for IP identifiers.

  • acme.sh supports EAB (External Account Bindings) as specified in RFC 8555 section 7.3.4, as well as with public key or certificate.

Prerequisites

The following lists prerequisites:

  • Linux-based OS, Mac OSX, or MS Windows including Cygwin. For more information, refer to the Tested OS section on acme.sh on GitHub.

  • System tools like curl or wget.

  • Super user permissions.

  • A web server like apache2 or Nginx.

Installation

After you have installed acme.sh package as described at https://github.com/acmesh-official/acme.sh, download the updated acme.sh file and overwrite the existing one in the root folder.

Example acme.sh EJBCA shell script file: acme-ejbca-7-7-1.sh.

SHA-256 checksum: 6635a452edf697e14753252e379adb2989904631c08fdbe35d84860740da4836

Post Installation

Set the ACME endpoint URL for acme.sh

Default ACME URL defined in acme.sh version of EJBCA is https://localhost:8442/ejbca/acme/directory.

You can use the --server option with acme.sh to specify this URL or edit the acme.sh line 24 $CA_EJBCA variable.

Create Challenge Directory for Your Web Server

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

images/s/dni64h/8703/189cb2l/_/images/icons/emoticons/warning.svg 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 acme.sh

To reset acme.sh, move or delete all files or folders below ~/.acme.sh.

$ rm -rf ~/.acme.sh/*

Show Help with acme.sh -h

Use the acme.sh help for detailed information and refer to more information on acme.sh on GitHub.

$ ./acme.sh -h

Run acme.sh Convenience Commands

acme.sh supports lots of single functions like generating account keys, domain keys, or CSRs, or call acme resources as well as convenience commands which process an entire ACME workflow with a single CLI call like the --issue option command.

acme.sh --issue option command workflow:

  1. If no ACME account is registered already, an account key pair is generated locally by acme.sh to register a new ACME account at the CA server (use the -ak option for account key specification). Otherwise acme.sh tries to recover an existing account using the existing account key stored on the system.

  2. acme.sh 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. acme.sh places the challenge token in the challenge directory of the local web server.

  4. acme.sh requests the CA servers challenge resource.

  5. EJBCA verifies the challenge response with HTTP.

  6. acme.sh deletes the challenge token.

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

  8. EJBCA enrolls and stores the certificate.

  9. acme.sh downloads the certificate using the URL in the order object received with the finalize resource response.

    $ ./acme.sh --issue -d example.com -w /var/www/html --insecure --force --debug 3 -k ec-256 -ak 2048

After acme.sh was reset, the script registers a new ACME account after it generated a new account key specified with the -ak option, to enroll a certificate for example.com with the key specification given with the -k option.

If you require additional subject-DN attributes or additional certificate extensions to fulfill the end entity and certificate profile restrictions, generate your CSR with the --create-csr option command and enroll your certificate using the -csr option.

Account Registration with Approvals and Certificate Enrollment

Select an approval profile in the ACME alias configuration field Require approval for account registration. For more information on ACME alias configuration fields, see ACME.

Make sure that you do not have an account already registered. For information on resetting acme.sh, see Reset acme.sh.

Repeat the convenience command described in Run acme.sh Convenience Commands above.

$ ./acme.sh --issue -d example.com -w /var/www/html --insecure --force --debug 3 -k ec-256 -ak 2048

acme.sh will log an error message as follows.

$ [...] Register account Error: {"detail":"A request to register your ACME account has been sent for approval. RequestID=694243043","type":"urn:ietf:params:acme:error:approvalRequiredForAccountRegistration"}

Repeat the command after your approval has been approved by the administrators specified in the approval profile. Your account is then registered and your certificate is enrolled.

Run acme.sh Commands

The following outlines acme.sh commands for handling ACME accounts and certificates.

Register an ACME Account

To register an ACME account, run:

$ ./acme.sh --register-account --insecure --force --email test@primekey.com

The register command can be used with approvals as well as EAB. Note that the acme.sh --issue option command does not seem to recognize the --eab options.

--email specifies the account contact information.

$ ./acme.sh --register-account --insecure --force --eab-kid 9UiJbZzO7WtuAU4IDsxNsNaMFl4 --eab-hmac-key Xs8Yi_fYdxWDRKupHMpjewjHAvduSAd1d5QeEKucs5E

acme.sh confirms the account registered showing the account thumbprint.

[...] Create account key ok.
[...] Registering account: https://localhost:8442/ejbca/acme/directory
[...] Registered
[...] ACCOUNT_THUMBPRINT='Fg4_hKmJafc0N_Gviqo-8Xj6GtTDiW4lASS8f6Gb9Lw'

Update an ACME Account

To update the account holders contact information:

$ ./acme.sh --update-account --insecure --force --email test@primekey.com

acme.sh confirms the account update showing the account URL (including the KID).

$ [...] account update success for https://localhost:8442/ejbca/acme/acct/KpKGJr3I3auSKxvQBK2PVA.

Deactivate an ACME Account

Deactivate the account if you do not want to enroll further certificates with this account.

$ ./acme.sh --deactivate-account --insecure --force

acme.sh confirms the account deactivation showing the account URL (including the KID).

$ [...] Deactivate update success for https://localhost:8442/ejbca/acme/acct/KpKGJr3I3auSKxvQBK2PVA.

Certificate Revocation

Revocation reasons can be specified from 0 (unspecified) to 10. For more information, refer to https://github.com/acmesh-official/acme.sh/wiki/revokecert.

$ ./acme.sh --revoke --domain example.com --ecc --revoke-reason 0

Certificate Renewal

Do not delete the certificate before renewal.

Keep in mind that you cannot use RANDOM usernames if the issuing CA enforces a unique subject-DN for each certificate enrolled.

$ ./acme.sh --renew --domain example.com --ecc --force

Certificate Removal

With the following option command, the certificate is removed from acme.sh certificate list.

$ ./acme.sh --remove --domain example.com --ecc

Note that the key pair, CSR, and certificate are not deleted.