en English
X

Select Language

Powered by Google TranslateTranslate

We hope you will find the Google translation service helpful, but we don’t promise that Google’s translation will be accurate or complete. You should not rely on Google’s translation. English is the official language of our site.

en English
X

Select Language

Powered by Google TranslateTranslate

We hope you will find the Google translation service helpful, but we don’t promise that Google’s translation will be accurate or complete. You should not rely on Google’s translation. English is the official language of our site.

SSL/TLS Certificate Issuance and Revocation with ACME

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

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.

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.

  1. Log into your SSL.com account. If you are already logged in, go to the Dashboard tab.
    Dashboard
  2. Click api credentials, located under developers and integration.
    API credentials link
  3. 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.
    Account/ACME Key and HMAC Key
  4. 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.Copy certbot command

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-rsa --manual-public-ip-logging-ok --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-rsa specifies SSL.com’s ACME server.
  • --manual-public-ip-logging-ok (optional) automatically allows public IP logging. If you skip this option, you will receive a prompt asking if you wish to allow it. Public IP logging is not required.
  • --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: 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.

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.

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 --manual-public-ip-logging-ok --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.

Using EJBCA Keys

Certbot does not support keypair and CSR generation for EDCSA keys, but you can manually generate a CSR with OpenSSL and then specify it in your Certbot command with the --csr option:

  1. Generate your CSR with OpenSSL (see this how-to for more details):
    openssl req -newkey ec:<(openssl genpkey -genparam -algorithm ec -pkeyopt ec_paramgen_curve:P-256) -keyout PRIVATEKEY.key -out MYCSR.csr
    
  2. Specify the CSR in your Certbot command (note that you will also have to change the value for --server to --server https://acme.ssl.com/sslcom-dv-ecc. Note also that when you specify the CSR, you do not need to include the domain name in your command:
    sudo certbot certonly --server https://acme.ssl.com/sslcom-dv-ecc --manual --agree-tos --email EMAIL-ADDRESS --manual-public-ip-logging-ok --no-eff-email --eab-hmac-key HMAC-KEY --eab-kid ACCOUNT-KEY --csr MYCSR.csr

When you use the --csr option, your certificate files will be saved in your current working directory and will have generic names (e.g. 0000_cert.pem).

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)

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

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.comwww.example.com, and info.example.com
    • example.comwww.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.

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:

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.

Share on twitter
Twitter
Share on facebook
Facebook
Share on linkedin
LinkedIn
Share on reddit
Reddit
Share on email
Email