SSL/TLS Certificate Issuance and Revocation with ACME

SSL.com Support Team

4 years ago

SSL.com customers can now use the popular ACME protocol to request and revoke SSL/TLS certificates.

ACME (Automated Certificate Management Environment) is a standard protocol for automated domain validation and installation of X.509 certificates, documented in IETF RFC 8555. As a well-documented standard with many open-source client implementations, ACME offers a painless way to provision websites or IoT devices such as modems and routers with publicly- or privately-trusted digital certificates and keep these certificates updated over time.

ACME isn’t just for websites! With an ACME-enabled issuing CA from SSL.com, IoT vendors can easily manage and automate validation, installation, renewal, and revocation of SSL/TLS certificates on ACME-capable devices.

Learn more about ACME for the IoT

This guide will show you how to:

Locate and retrieve the credentials you will need to request certificates with ACME.
Use Certbot to manually request SSL/TLS certificates via the HTTP-01 and DNS-01 challenge methods.
Revoke certificates with Certbot.

Note:
You can use many other ACME clients, including Kubernetes cert-manager, with SSL.com’s ACME service.
acme4j client can now use SSL.com ACME services on this repository: https://github.com/SSLcom/acme4j
Please refer to your software provider’s documentation for instructions for other non-Certbot ACME clients.

Install Certbot

This guide assumes you are working on a computer that has Certbot installed. Certbot is a free and open-source tool, developed by the Electronic Frontier Foundation (EFF), that you can use to request or revoke SSL/TLS certificates from SSL.com via the ACME protocol. Certbot can be run on a variety of platforms, including Linux, macOS, and Windows.

If you have snapd installed, you can use this command for installation:
```
sudo snap install --classic certbot
```
If /snap/bin/ is not in your PATH, you will also need add it or run a command like this:
```
sudo ln -s /snap/bin/certbot /usr/bin/certbot
```

If you need more information about installing Certbot on your system, please refer to the EFF’s documentation.

Go to top

Retrieve ACME Credentials

Before using ACME to request a certificate, you will need to retrieve your Account Key and HMAC Key from your SSL.com account.

SSL.com’s Reseller and Volume Purchasing partners can generate ACME credentials for their customers. Read this how-to for full instructions.

Log into your SSL.com account. If you are already logged in, go to the Dashboard tab.
Click api credentials, located under developers and integration.
You will need your Account/ACME Key and HMAC Key to request certificates. Click the clipboard icon () next to each key to copy the value to the clipboard.
You can also copy a Certbot command pre-filled with your email address, Account/ACME key and HMAC key by clicking the clipboard icon () next to cli command, below ACME Certbot. This pre-formatted command will order a certificate via the HTTP-01 challenge method.

Go to top

Manually Request an SSL/TLS Certificate

Now that you have retrieved your credentials, you can request a certificate via the certbot command. Certbot supports two domain validation (DV) methods: HTTP-01 and DNS-01.

HTTP-01 Challenge Method

HTTP-01 is the most commonly-used challenge method used with ACME and Certbot. When you request a certificate in this way, Certbot will generate a token that you can use to create a publicly-accessible file on your website. SSL.com’s ACME server will then verify the file via HTTP and issue a signed certificate if it is correct.

Requirements: The HTTP-01 method requires that you have access to your web server, and that the site is available over port 80 via HTTP. You will also need sudo privileges on the computer.

To manually retrieve a certificate, use the following command. Replace values in ALL CAPS with your actual values. (As noted above, you can also copy and paste a certbot command that does this from your portal account):

sudo certbot certonly --manual --server https://acme.ssl.com/sslcom-dv-ecc --config-dir /etc/ssl-com --logs-dir /var/log/ssl-com --agree-tos --no-eff-email --email EMAIL-ADDRESS --eab-hmac-key HMAC-KEY --eab-kid ACCOUNT-KEY -d DOMAIN.NAME

Breaking the command down:

sudo certbot runs the certbot command with superuser privileges.
certonly requests to retrieve an certificate, but not install it.
--manual specifies to run Certbot interactively.
--server https://acme.ssl.com/sslcom-dv-ecc specifies SSL.com’s ACME server.
--config-dir /etc/ssl-com (optional) sets the configuration directory.
--logs-dir /var/log/ssl-com (optional) sets the directory for logs.
--agree-tos (optional) agrees to the ACME subscriber agreement. You can omit this if you want to agree interactively.
--no-eff-email (optional) indicates that you do not want share your email address with the EFF. If you omit this you will be prompted with the option to share your email address.
--email EMAIL-ADDRESS provides a registration email address. You may specify multiple addresses, separated by commas.
--eab-hmac-key HMAC-KEY specifies your HMAC key.
--eab-kid ACCOUNT-KEY specifies your account key.
-d DOMAIN.NAME specifies the domain name that the certificate will cover. Note that you can use the -d DOMAIN.NAME option multiple times in your command to add domain names to your certificate. Certbot will require you to create a challenge file for each domain name requested. Please see the section on certificate types and billing below to see how different combinations of domain names map to SSL.com certificate types and their corresponding pricing.

Note: Certbot 2.0.0 or newer defaults to generating ECDSA for new certificates. The above command will generate an ECDSA keypair and certificate. To use RSA keys instead:

Change the --server value in the command to https://acme.ssl.com/sslcom-dv-rsa.
Add --key-type rsa to the command.

When you first run the above certbot command, ACME account info will be stored on your computer in the configuration directory (/etc/ssl-com in the command shown above. On future runs of certbot, you can omit the --eab-hmac-key and --eab-kid options because certbot will ignore them in favor of the locally stored account info.

If you need to associate your ACME certificate orders for the computer with a different SSL.com account, you should remove this account information from your computer with the command sudo rm -r /etc/ssl-com/accounts/acme.ssl.com (or, if you omitted the optional --config-dir option, sudo rm -r /etc/letsencrypt/accounts/acme.ssl.com).

When you run the above command, you should receive instructions to create a validation file:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Create a file containing just this data:

cr1rsRTImVz_s7HHk7biTQ.9mOlJPgZ8D97HojOHnhD6hYeZZOPDUDNMxchFUNJQvI

And make it available on your web server at this URL:

http://DOMAIN.NAME/.well-known/acme-challenge/cr1rsRTImVz_s7HHk7biTQ

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Press Enter to Continue

Create the file and save it in a location on your web server where it can be accessed via HTTP over port 80 at the URL shown, then press Enter.

Note: The HTTP-01 challenge may require a filename beginning with a dash (-) character. In this case you may need specify the directory when creating your file to prevent the shell from interpreting the dash (e.g. vim ./-r1rsRTImVz_s7HHk7biTQ).

If all of your information is correct, you should receive a confirmation message showing the locations of your certificate chain and private key:

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
   /etc/ssl-com/live/DOMAIN.NAME/fullchain.pem
   Your key file has been saved at:
   /etc/ssl-com/live/DOMAIN.NAME/privkey.pem
   Your cert will expire on 2021-10-05. To obtain a new or tweaked
   version of this certificate in the future, simply run certbot
   again. To non-interactively renew *all* of your certificates, run
   "certbot renew"

You can now configure your web server to access the new certificate and private key.

Go to top

DNS-01 Challenge Method

The DNS-01 challenge method is trickier to use than HTTP-01, but can be more convenient for use on multiple web servers. In this method, Certbot will provide a token that you use to create a DNS TXT record under the domain name that the certificate will protect.

Requirements: The DNS-01 method requires that you have the ability to create DNS records for your website’s domain name.

The following command will request a certificate for DOMAIN.NAME via the DNS-01 challenge method:

sudo certbot certonly --manual --server https://acme.ssl.com/sslcom-dv-rsa --agree-tos --no-eff-email --email EMAIL-ADDRESS --eab-hmac-key HMAC-KEY --eab-kid ACCOUNT-KEY --preferred-challenges dns -d DOMAIN.NAME

Note: You can use the -d DOMAIN.NAME option multiple times in your command to add domain names to your certificate. Certbot will require you to create a separate DNS TXT record for each domain name requested. You do not have to wait for each TXT record to propagate before pressing Enter until you reach the final challenge. Please see the section on certificate types and billing below to see how different combinations of domain names map to SSL.com certificate types and their corresponding pricing.

This command is the same as the one from the HTTP-01 section, but adds the --preferred-challenges dns option. When you run the command, you will receive instructions for creating a DNS record:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Please deploy a DNS TXT record under the name _acme-challenge.DOMAIN.NAME with the following value: -87YKoj3sQZB4rVCMZTiifl9QJKYm2eYYymAkpE0zBo Before continuing, verify the record is deployed. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Press Enter to Continue

Create the DNS TXT record and wait for it to propagate. (whatsmydns.net is a convienient tool to check for DNS propagation). Note that the underscore character (_) at the beginning of the record name is required. When the record has propagated worldwide, press Enter.

If you are requesting a wildcard certificate (e.g. *.example.com) you will need to request the base domain name separately if you wish to protect it too (for example -d *.example.com -d example.com). In such a case you will need to create two TXT records with the same name (_acme-challenge.example.com).

If all of your information is correct, you should receive a confirmation message showing the locations of your certificate chain and private key:

IMPORTANT NOTES: - Congratulations! Your certificate and chain have been saved at: /etc/ssl-com/live/DOMAIN.NAME/fullchain.pem Your key file has been saved at: /etc/ssl-com/live/DOMAIN.NAME/privkey.pem Your cert will expire on 2021-10-05. To obtain a new or tweaked version of this certificate in the future, simply run certbot again. To non-interactively renew *all* of your certificates, run "certbot renew"

You can now configure your web server to access the new certificate and private key.

Go to top

Certificate Renewal (Manual)

For manually-issued certificates (as described in this guide), certificate renewal is accomplished by simply repeating the command used to request the certificate. Certbot does provide a renew subcommand, but it will produce an error on an attempt to use it with certificates requested with the --manual option:

sudo certbot renew --force-renewal
Saving debug log to /var/log/ssl-com/letsencrypt.log

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Processing /etc/ssl-com/renewal/DOMAIN.NAME
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Could not choose appropriate plugin: The manual plugin is not working; there may be problems with your existing configuration.
The error was: PluginError('An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively.',)
Attempting to renew cert (DOMAIN.NAME) from /etc/ssl-com/renewal/DOMAIN.NAME.conf produced an unexpected error: The manual plugin is not working; there may be problems with your existing configuration.
The error was: PluginError('An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively.',). Skipping.
All renewal attempts failed. The following certs could not be renewed:
  /etc/ssl-com/live/DOMAIN.NAME/fullchain.pem (failure)

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

All renewal attempts failed. The following certs could not be renewed:
  /etc/ssl-com/live/DOMAIN.NAME/fullchain.pem (failure)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1 renew failure(s), 0 parse failure(s)

Go to top

Certificate Revocation

Revoke a certificate with certbot revoke. Replace the certificate path in ALL CAPS with your actual values (for example, /etc/ssl-com/live/example.com/cert.pem). If you did not specify a custom --config-dir and --logs-dir when requesting the original certificate, omit these options.

sudo certbot revoke --server https://acme.ssl.com/sslcom-dv-rsa --cert-path /PATH/TO/cert.pem --config-dir /etc/ssl-com --logs-dir /var/log/ssl-com

You will be prompted as to whether you would also like to delete the revoked certificate:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you like to delete the cert(s) you just revoked, along with all earlier
and later versions of the cert?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es (recommended)/(N)o: Y

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Deleted all files relating to certificate DOMAIN.NAME.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Note: Some users might get this error while attempting to revoke a certificate using SSL.com’s ACME endpoint:

Unable to register an account with ACME server. Error returned by the ACME server: Something went wrong. We apologize for the inconvenience.

Try the following to resolve the error:
a) Specify the certificate’s private key path to sign the revocation request.
Example: --key-path /PATH/TO/privkey.pem
b) If you used a custom directory, specify the directory you used when you issued the certificate:

--config-dir

Go to top

Certificate Types and Billing

All SSL/TLS certificates issued via ACME by SSL.com are one-year certificates. The SSL.com certificate type you will receive (and be billed for) depends on the number and type of domain names requested:

Basic SSL: One domain name, or domain name plus www subdomain (e.g. example.com and www.example.com).
- Note that if you wish to protect both the base domain name and www, you must include both in your Certbot command (e.g. -d example.com -d www.example.com).
Wildcard SSL: One wildcard domain name, or one wildcard domain name plus base domain name (e.g. *.example.com and example.com).
Premium SSL: Base domain name and one to three non-wildcard subdomains. (Exception: As noted above, base domain plus www subdomain [and no others] will be billed as Basic SSL.) For example:
- example.com and info.example.com
- example.com, www.example.com, and info.example.com
- example.com, www.example.com, info.example.com , and store.example.com
Multi-Domain UCC/SAN SSL: Any other combination of domain names. For example:
- Base domain name and more than three subdomains
- Two or more wildcard and/or non-subdomain domain names

Partipants in SSL.com’s Reseller and Volume Purchasing Program will be billed at the discounted rate associated with their pricing tier.

Go to top

For More Information

There’s a lot more you can do with the ACME protocol (with or without Certbot). Please refer to the following resources for much more information:

Need more help with your SSL.com account?

Thank you for choosing SSL.com! If you have any questions, please contact us by email at Support@SSL.com, call 1-877-SSL-SECURE, or just click the chat link at the bottom right of this page. You can also find answers to many common support questions in our knowledgebase.