Nexus Documentation

Space shortcuts

Page tree

Versions Compared

Old Version 5

changes.mady.by.user Karolin Hemmingsson

Saved on

compared with

New Version 6

changes.mady.by.user Karolin Hemmingsson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: minor

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


Expandall

Prerequisites

Expand
titlePrerequisites

The following prerequisites apply:

Step-by-step instruction

Configure ACME in Protocol Gateway

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

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

    Code Block
    titleExample: CM domain in hosts file 
    127.0.0.1 cm.local test.cm.local



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


Expand
titleCreate 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. 
Info
titleAbout 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.



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

      Info

      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.  
Code Block
titleExample: ACME.properties
start = true
handler.0.tokenProcedure = ACME TLS Web Server Token
handler.0.baseUrl = https://cm.local:8443/pgwy/acme
handler.0.externalAccountRequired = true



Expand
titleRestart Tomcat
  1. 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.

Expand
titleInstall 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.
Note

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



Expand
titleSet up TLS

To set up TLS communication: 

  1. Convert the SystemCA certificate to .pem format:

    Code Block
    languagepowershell
    titleExample: 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. 


Expand
titlePreregister 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

Expand
titleRequest certificate via Certbot

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

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

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

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

      Code Block
      titleExample: Request certificate with Certbot
      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.


Expand
titleRevoke certificate

To test revocation using Certbot: 

  1. With Certbot, run the revoke command to revoke the certficate test.cm.local: 
Code Block
titleExample: Revoke test certificate
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.


Related information