Global Fields

The following fields are defined globally for all ACME operations.

Alias Specific Fields

Example of ACME Alias configuration.

The following table lists ACME specific fields for each individual alias.

Example Scenarios

HTTP Validation Scenario

1. Issue certificate for an identifier (example.com) using HTTP validation:

   Setup a local HTTP server (for example Apache with the default working directory /var/www/html). Add the following virtual host under /etc/apache2/sites-available/example.com.conf:
   

   <VirtualHost *:80>

   ServerName example.com

    

   DocumentRoot "/var/www/"

    

   </VirtualHost>

   Enable the site using the command:

   $ sudo a2ensite example.com

   Then run:

   $ sudo service apache2 reload

   Next, restart Apache:

   $ sudo /etc/init.d/apache2 restart

   Then add the following line to your /etc/hosts file:

   127.0.0.1 example.com

   Create the directory structure of .well-known/acme-challenge inside /var/www/example/ and change its permissions to 755 recursively.

   mkdir -p .well-known/acme-challenge

    

   chmod 755 -R .well-known/

2. Having Certbot installed on your machine, try the following command (EJBCA should be up and running with ACME enabled and with an ACME alias configured with appropriate end entity profile):

   $ sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory certonly --webroot -w /var/www/ -d example.com --agree-tos --email test@example.com --no-eff-email --noninteractive

   The command should run successfully and in the display a message similar to the following:

   IMPORTANT NOTES:
    - Congratulations! Your certificate and chain have been saved at:
    /etc/letsencrypt/live/example.com/fullchain.pem
    Your key file has been saved at:
    /etc/letsencrypt/live/example.com/privkey.pem
    Your cert will expire on 2020-08-21. 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"
    - If you like Certbot, please consider supporting our work by:

   Go to EJBCA Admin Web and search for End Entities, there should be one with the status Generated and CN = example.com.

   The error message The client lacks sufficient authorization :: The client lacks sufficient authorization indicates a conflict between the new account creation and existing ACME accounts. To resolve, remove everything under /etc/letsencrypt/live, /etc/letsencrypt/accounts and /etc/letsencrypt/keys and try again.

3. If you want to issue a certificate containing multiple domains (for instance, example.com and example.org), set up another Apache virtual host as follows:

   <VirtualHost *:80>

   ServerName "example.org"

   DocumentRoot "/var/www/"

   </VirtualHost>

   Repeat the steps mentioned above to enable it and add it to your hosts.

   Next, issue the following command and ensure to remove the live, keys and account directories of certbot otherwise it will ask for expansion of the already existing certificate. Note that the domains specified using -d are comma separated.

   sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory certonly --webroot -w /var/www/ -d example.com,example.org --agree-tos --email test@example.com --no-eff-email --noninteractive

   This will result in a certificate which covers both the example.com and example.org domains. To verify, decode the produced certificate .pem file and observe that the SAN section includes two domains as two different dnsNames.

4. To revoke the certificate issued in the step above, run the following command:

   $ sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory revoke --cert-name example.com --reason keycompromise

   If asked for deleting the just issued certificate, reply with Y. Alternatively use the option switch --no-delete-after-revoke and delete the certificates for the domain afterwards with the certbot delete command. The following success message must be shown:

   Congratulations! You have successfully revoked the certificate that was located at /etc/letsencrypt/live/example.com/fullchain.pem

   Go to EJBCA Admin Web and check the status for the corresponding End Entity certificate and make sure it is revoked.

5. In order to issue a certificate for a wildcard domain do as follows:
   First you need to enable the wildcard certificate issuance via Acme Configuration alias page.
   Then run the same command as in step two providing a wildcard domain as identifier.

   $ sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory certonly --webroot -w /var/www/html/ -d *.example.com

   The rest of procedure should be same as above.

DNS Validation Scenario

1. Issue certificate for an identifier (allow.klaan.nu) using Domain Name System Security Extensions ( DNSSEC ) validation:
   Make sure you have a DNS server setup which you can add TXT records to. In this example, dnsmasq is used, included in most Linux distributions.

   The EJBCA ACME server currently supports DNSSEC validation and this example uses allow.klaan.nu to be able to pass DNSSEC validation.

2. To issue the certificate, run the following command in the command line:

   $ sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory certonly --manual --preferred-challenges=dns -d allow.klaan.nu

   The --manual flag is used to run Certbot interactively and allow preparing the DNS server with the DNS challenge offered by the ACME server.

   Agree to your IP being logged by replying Yes to the following:

   Are you OK with your IP being logged?
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   (Y)es/(N)o:

   Certbot displays the TXT record challenge offered by the ACME server which have to be provisioned in the DNS server. Before pressing Enter, run the following command to provision the TXT record in dnsmasq:

   $ sudo dnsmasq --port="1453" --txt-record="_acme-challenge.allow.klaan.nu, pULO3RjCbzqjWH0JK2FQ5BDe-5SI2Eo2Vn1l_fmrtdk" --listen-address="127.0.0.1" --interface="lo" --bind-interfaces

   The port number used above is just an example. Note that the port number must equal the port set for the ACME Alias currently used by the EJBCA ACME server, configured in Admin Web>System Configuration>ACME Configuration. In addition, the DNS Resolver field needs to be set to localhost in the ACME Configuration Alias page, see Alias Specific Fields.

   After running the above command, press Enter in the Certbot command prompt to continue. A message similar to the following is displayed for a successful certificate issuance:

   IMPORTANT NOTES:
    - Congratulations! Your certificate and chain have been saved at:
      /etc/letsencrypt/live/allow.klaan.nu/fullchain.pem
      Your key file has been saved at:
      /etc/letsencrypt/live/allow.klaan.nu/privkey.pem
      Your cert will expire on 2020-08-21. 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"
    - If you like Certbot, please consider supporting our work by:
   
      Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
      Donating to EFF:                    https://eff.org/donate-le
   

   Ensure that the certificate is issued in EJBCA by checking that the Admin Web End Entity Search page includes a row with CN equal to allow.klaan.nu and a valid certificate.

3. To revoke the certificate issued in the previous step, run:

   $ sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory revoke --cert-path /etc/letsencrypt/live/allow.klaan.nu/fullchain.pem

   The following message displays if successful:

   Congratulations! You have successfully revoked the certificate that was located
   at /etc/letsencrypt/live/allow.klaan.nu/fullchain.pem

   Make sure that the certificate is revoked with the reason Unspecified in EJBCA by checking its status in the Admin Web End Entity Search page.

4. To issue a certificate for a wildcard domain do as follows:
   First enable the wildcard certificate issuance via Acme Configuration alias page.
   Then issue the following (example) command.

   $ sudo certbot --no-verify-ssl --server https://localhost:8442/ejbca/acme/directory certonly --manual --preferred-challenges=dns -d *.allow.klaan.nu

   The rest of the procedure is similar to the above.