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:
- 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:
- Set Procedure name to TLS Web Server Certificate.
- In Issuing CA, select Device Issuing CA.
- In Certificate format, select server certificate.
- In Authority information access, add ad-ocsp = <URL to OCSP Responder>.
- In Extended key usage, add TLS Server Authentication.
Create token procedures
Create token procedures, see Create token procedure in Certificate Manager:
- Create a token procedure for ACME preregistration:
- Set Procedure name to ACME preregistration.
- In Storage profile, select PKCS10.
- In Certificate procedures, select the certificate procedure you just created, that is TLS Web Server Certificate.
- In Input view, select GPIV 13 - Save and Search ACME Pre-Registrations.
- Create a token procedure for ACME TLS web servers:
- Set Procedure name to ACME TLS Web Server Token.
- In Storage profile, select PKCS10.
- In Certificate procedures, select the certificate procedure you just created, that is TLS Web Server Certificate.
- 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:
- Open \Nexus\cm-gateway\conf\ACME.properties for editing. For more information, see acme.properties.
- Modify the following properties:
- Enable ACME by setting
start
totrue
. - Set
handler.0.tokenProcedure
toACME TLS Web Server Token
. - Set
handler.0.baseUrl
tohttps://cm.local:8443/pgwy/acme
. Set
handler.0.externalAccountRequired
totrue
. For more information on how to configure verifications of certificate requests in .properties files, see Certificate request verifications in Protocol Gateway.
- Enable ACME by setting
If needed, scramble sensitive parameters in the configuration file. See Scramble sensitive data in configuration files in Protocol Gateway.
- 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:
- 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.)
- 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:
Convert the SystemCA certificate to .pem format:
Example: Convert SystemCA to .pem formatC:\Nexus\cm\server\certs>certutil -encode SystemCA.cer cacert.pem Input length = 822 Output length = 1188 CertUtil: -encode command completed successfully.
- 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:
- Go to the Order tab.
- 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.
- Enter the following:
- Enter a KeyID, a unique number to identify the device.
- By HMAC key, click Generate to get an HMAC key.
- In Allowed domains, enter cm.local.
For more information, see Allowed domain names for preregistration in Certificate Manager. - In State, select Open.
- 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.