ACME with acme.sh

ENTERPRISE

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.6. Download or install from the GitHub repository acme.sh on GitHub.

Do not use an acme.sh version prior to 3.0.6 due to the vulnerability described on  acme.sh on GitHub.

Supported Features

The following highlights supported features:

• acme.sh supports EJBCA approvals for ACME account management.
• acme.sh supports certificate enrollment for IP identifiers as specified in RFC 8738.
• acme.sh supports certificate enrollment for DNS identifiers with the tls-alpn-01 challenge as specified in RFC 8737.
• 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

Download and unpack the latest release from https://github.com/acmesh-official/acme.sh.

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.

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.

   CODE

   $ ./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 ACME with acme.sh#Reset acme.sh.

Repeat the convenience command described in ACME with acme.sh#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 issuance with the http-01 challenge

Certificates can be issued using the http-01 challenge. acme.sh stores the challenge authorization for the DNS or IP identifier in the local web server's root.

$ ./acme.sh --issue --insecure --webroot /var/www/html -d example.com

Certificate issuance with the tls-alpn-01 challenge

Certificates for DNS identifiers can be issued using the tls-alpn-01 challenge in standalone mode. acme.sh launches a TLS server with a self-signed certificate holding the challenge authorization for the identifier on port 443.

The challenge is performed against the IP resolved by the DNS service specified in the ACME alias fields 'DNS Resolver' and 'DNS Port'. DNSSEC is optional and in case must be supported by the DNS service.

$ ./acme.sh --issue --insecure --alpn -d example.com

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