This article describes a configuration example of the ACME protocol in Protocol Gateway. For more information, see ACME support in Certificate Manager.

Prerequisites

• Protocol Gateway must be installed. See Install Protocol Gateway.
• The Protocol Gateway license must include ACME. 
• For preregistration. either of the following installations and licenses must be available: 
  • REST API or RA client with Order tab or CM SDK.
• Initial configuration of Protocol Gateway must be done. See Initial configuration of Protocol Gateway.
• Tomcat must be configured for TLS client authentication. See Configure Tomcat for TLS client authentication in Protocol Gateway.

Configure ACME in Protocol Gateway

For demo use cases: Add CM domain to Windows hosts file

For demo use cases, when there is no real DNS set up, follow these steps to point out the CM domain:  

1. Open the file C:\Windows\System32\drivers\etc\hosts for editing. 

Add the Certificate Manager domain and machine to point to 127.0.0.1 (or to be resolvable via DNS).

127.0.0.1 cm.local test.cm.local

Create TLS server certificate procedure

Create a certificate procedure for TLS server certificates, see Create certificate procedure in Certificate Manager:

1. Set Procedure name to TLS Web Server Certificate.  
2. In Issuing CA, select Device Issuing CA. 
3. In Certificate format, select server certificate. 
4. In Authority information access, add ad-ocsp = <URL to OCSP Responder>.
5. In Extended key usage, add TLS Server Authentication.  

Create token procedures

Create token procedures, see Create token procedure in Certificate Manager:

1. Create a token procedure for ACME preregistration:
   1. Set Procedure name to ACME preregistration. 
   2. In Storage profile, select PKCS10.
   3. In Certificate procedures, select the certificate procedure you just created, that is TLS Web Server Certificate. 
   4. In Input view, select GPIV 13 - Save and Search ACME Pre-Registrations.  
2. Create a token procedure for ACME TLS web servers:
   1. Set Procedure name to ACME TLS Web Server Token. 
   2. In Storage profile, select PKCS10.
   3. In Certificate procedures, select the certificate procedure you just created, that is TLS Web Server Certificate. 
   4. In Input view, select GPIV 14 - Save and Search ACME Accounts. 

About GPIV 13 and 14

GPIV 13 is used to handle the so called external ACME accounts, i.e. pre-registrations according to https://tools.ietf.org/html/rfc8555#section-7.3.4

GPIV 14 is used to handle the actual ACME account. https://tools.ietf.org/html/rfc8555#section-7.3

GPIV 14 is used to revoke an account from the 'server side'. Meaning that the account can no longer be used to renew or create new certificates.

The actual ACME accounts are created in the client - server workflow. It is not done beforehand. That is the purpose of the Pre-registrations. To limit the service to only allow "pre-authorized" clients to create accounts and get certificates. So GPIV 14 is only used by an administrator to disable the acme account from the server side, for example if a client has gone rogue, or been decommissioned with out finalizing the workflow by revoking itself.

Configure ACME in Protocol Gateway

To set the properties for the ACME protocols: 

1. Open \Nexus\cm-gateway\conf\ACME.properties for editing. For more information, see acme.properties.
2. Modify the following properties: 
   
   1. Enable ACME by setting start to true. 
   2. Set handler.0.tokenProcedure to ACME TLS Web Server Token.
   3. Set handler.0.baseUrl to https://cm.local:8443/pgwy/acme.

   4. Set handler.0.externalAccountRequired to true. For more information on how to configure verifications of certificate requests in .properties files, see Certificate request verifications in Protocol Gateway.

3. If needed, scramble sensitive parameters in the configuration file. See Scramble sensitive data in configuration files in Protocol Gateway.

4. Save the file.  

start = true
handler.0.tokenProcedure = ACME TLS Web Server Token
handler.0.baseUrl = https://cm.local:8443/pgwy/acme
handler.0.externalAccountRequired = true

Restart Tomcat

Restart the Tomcat service. 

Set up Certbot ACME client

This example shows how to use Certbot as the ACME client. For more information and examples with Kubernetes and Cert-manager, see Examples - Use ACME clients with Certificate Manager.

Install certbot for Windows client

An ACME client must be installed. The certbot client is recommended: 

1. Download the latest version of certbot from https://certbot.eff.org/lets-encrypt/windows-other.html. (Scroll down to point 4 to find the installer.) 
2. Run the installer.

Certbot version 0.29.0 or later is required to use the parameters --eab-kid and --eab-hmac-key (see below).

Set up TLS

To set up TLS communication: 

1. Convert the SystemCA certificate to .pem format:

   Example: Convert SystemCA to .pem format

   C:\Nexus\cm\server\certs>certutil -encode SystemCA.cer cacert.pem
   Input length = 822
   Output length = 1188
   CertUtil: -encode command completed successfully.

2. For Certbot to trust the Officer and System CA, move the new .pem file to C:\Program Files (x86)\Certbot\pkgs\certifi\cacert.pem. to replace the default cacert.pem file. 

Preregister ACME device

In Registration Authority (RA) in Certificate Manager, preregister an ACME device: 

1. Go to the Order tab.
2. In the Input view drop-down list, select the token procedure ACME preregistration, that is configured to use the input view GPIV 13 - Save and Search ACME Pre-Registrations.
3. Enter the following: 
   1. Enter a KeyID, a unique number to identify the device.
   2. By HMAC key, click Generate to get an HMAC key. 
   3. In Allowed domains, enter cm.local.
      For more information, see Allowed domain names for preregistration in Certificate Manager.
   4. In State, select Open. 
4. Copy the KeyID and HMAC key to use them in a Certbot command in the next task. 

NOTE:

This article does not cover how the KeyID and HMAC key are shared beforehand with ACME clients, since it is handled differently for each installation and organization.

ACME devices can also be preregistered using CM SDK or Certificate Manager (CM) REST API. For example code, see RegistrationExample.java distributed in the CM SDK.

Test the ACME setup via Certbot

Request certificate via Certbot

To test the ACME setup, request a certificate via Certbot: 

With Certbot, run the certonly command to request a certificate for the registered device: 

In --eab-kid, enter the KeyID that you copied from the registered device. 

In --eab-hmac-key, enter the HMAC key that you copied from the registered device. 

C:\Program Files (x86)\Certbot\bin>certbot certonly --agree-tos --email test@cm.local --domain test.cm.local --server https://cm.local:8443/pgwy/acme/directory --eab-kid 2 --eab-hmac-key UGmAUMn3yWlPev1ahn-Hi3b9Qg-C1c_4jf-IQGkNa-E --preferred-challenges http

For a certbot example without preregistration, see Examples - Use ACME clients with Certificate Manager.

Revoke certificate

To test revocation using Certbot: 

With Certbot, run the revoke command to revoke the certficate test.cm.local: 

C:\Program Files (x86)\Certbot\bin>certbot revoke --cert-name test.cm.local --email test@cm.local --server https://cm.local:8443/pgwy/acme/directory

Saving debug log to C:\Certbot\log\letsencrypt.log
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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 test.cm.local.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Congratulations! You have successfully revoked the certificate that was located
at C:\Certbot\live\test.cm.local\fullchain.pem

For more information, see Requirements to revoke certificates issued by ACME account.