How can we help?

Certificate Management using ACME

Gabriela Peralta - Versasec
Gabriela Peralta - Versasec
  • Updated

Introduction

From version 6.0, support has been added for the standard Automatic Certificate Management Environment (ACME). This means that it will be possible to manage the issuance and lifecycle of certificates from vSEC:CMS. Adding support for ACME is ideal for managing certificates that are issued as web and application certificates where it is challenging to manage and monitor such certificates with regards to issuance, renewal and revocation.

Combined with our current vSEC:CMS features, ACME support will provide a powerful and flexible configuration along with monitoring and management for ACME issued certificates, from TLS/SSL web server certificates to IoT device certificates and more. 

 

ACME_2.png
This article will describe how you can setup and configure vSEC:CMS such that you will be able to issue and manage the lifecycle of an TLS web server certificate. We will use Microsoft CA (MS CA) and a win-acme client for this article.

vseccms-acme.png

Setup

A number of steps need to be performed before you can issue and manage your TLS web server certificate.

Note
It is expected that you have already installed vSEC:CMS and that it is configured to be used with an MS CA. Additionally, it is expected that vSEC:CMS service is running under a dedicated Windows service account.

Install and Configure vSEC:CMS ACME

From the DOWNLOADS page on vSEC:CMS support portal download the ACME package.

Untitled.png

Depending on what version of vSEC:CMS server you are running, install the 32-bit or 64-bit version on the server where vSEC:CMS is installed. This will install an ACME-compliant (RFC 8555) service.

Configure MS CA TLS Web Server Certificate

A TLS web server certificate needs to be available from the MS CA. In this section we will describe how you can setup such a template on MS CA and make it available to vSEC:CMS.

From the MS CA management dialog right click Web Server and select Duplicate Template.

Untitled.png

From the Compatibility tab select Windows Server 2008 R2 from the Certification Authority drop-down list and Windows 8.1/Windows Server 2012 R2 from the Certificate Recipient drop-down list.

Untitled.png

From the General tab enter a template name and provide a validity period like below.

Untitled.png

From the Cryptography tab configure similar to below.

Untitled.png

From the Security tab add the Windows service account that vSEC:CMS service is running under and make sure to grant Enroll.

Untitled.png

Click Ok to save and close the template.

From the MS CA console window right click Certificate Templates and select New - Certificate Template to Issue and select the template just created.

Untitled.png

Configure vSEC:CMS for ACME Support

Log into vSEC:CMS Admin console. Navigate to Options - Connections - Certificate Authorities and select the MS CA connection that you are using. Click Edit and click the Templates button. Click Update and you should see the template created earlier appear in the available list of certificate templates. Click Cancel to go back.

Untitled.png

Additionally, make sure the issuer DN is populated similar to below. If this field is empty click Get and select your issuer DN value.

Untitled.png

Navigate to Options - Connections - ACME Service. Configure similar to below.

Important
It is required to have a server TLS/SSL certificate available on the vSEC:CMS server. Enable Use SSL checkbox and select the available TLS/SSL server certificate. The ACME client will connect to the server and it is required that TLS/SSL is used.

Untitled.png

Navigate to Templates - Certificate Management Templates and click Add.

Enter a template name and select ACME certificate management template from the Certificate Templates drop-down list. Enable Connect CA checkbox and select your CA from the Certificate authority drop-down list. Select the CA certificate template created earlier from the Certificate template drop-down list. Leave all other settings as is and save.

Untitled.png

Make a note of the ID as shown below as this will be required when configuring the win-acme client below.

Untitled.png

Install and Configure win-acme Client

Download the latest win-acme client and put it on the host where you want to issue your TLS web server certificate. 

Using a text editor open the file named settings.json. Edit the settings:

"DefaultBaseUri", "DefaultBaseUriTest" and "DefaultBaseUriImport"

and point them to the vSEC:CMS server. For example, if your vSEC:CMS server is installed on server named win-192bg93tj8o.paul-lab.com and you configured the ACME connection as described above then enter a value: "https://win-192bg93tj8o.paul-lab.com:50443/2162689/" where 2162689 is the ID we noted down earlier. Your settings should look similar to below.

Untitled.png

Search for the line RenewalDays and replace the value with something lower than the one set in the certificate template (in this example the value 25 is lower than 30 which is set in the certificate template).

Untitled.png

Ensure that the DNS server is set under the Validation section (in this example it is using the hosts file that is contained in the C:\Windows\System32\drivers\etc folder, thus we use the loopback address 127.0.0.1).

Untitled.png

Search for this section highlighted below and make sure to enter the full path to the folders for both PemFiles and PfxFile. This will of course will depend where you installed the win-acme client on your host so adjust accordingly. 

Untitled.png

Save the changes and close the settings.json file.

TLS Web Server Certificate Lifecycle

Now we are ready to create a TLS web server certificate on the host where we have setup the win-acme client. Open a command prompt as administrator and navigate to the location where you installed the win-acme client. Run the command below:

Command
wacs.exe --target manual --host paul-laptop.local --store pemfiles --emailaddress acms-admin@versasec.com

Where

  • --host is the fully qualified host name for the TLS web server certificate;
  • --store specifies which store to use;
  • --emailaddress is the email address that is registered with vSEC:CMS for the order and will be used by win-acme to notify if the renewal fails (for whatever reason).

Untitled.png

Note
You should refer to the online win-acme documentation for extensive details on the different parameters that can be used here.

You will see files created in the PemFiles folder (configured earlier above). These can then be used as your TLS web server certificate.

Additionally, a Windows automatic scheduled task will be created (you can see this in the Windows Task Scheduler) which will run daily to check if a renewal needs to be triggered. In our example configuration the renewal will be trigger 25 days before the TLS web server certificate will expire.

On vSEC:CMS side, you will see a number of entries under Repository - ACME.

In Account repository you can see the accounts created and the transaction log history for those accounts. These accounts are the email address used when running the win-acme command earlier.

Untitled.png

In Order repository you can see the orders that have come through from the different win-acme clients. Select an entry and click the Details button to see more information about the order.

Untitled.png

Navigate to Repository - Certificates and you will see the certificate(s) issued from the win-acme client. Select an entry and additional functionality will be available.

Troubleshooting Tips

If you are facing issues managing/issuing certificate(s) from a host where you are running win-acme here are some tips that can help to resolve any issues you face.

  • Make sure that your firewall is not blocking communication to the vSEC:CMS ACME service;
  • Completely delete or remove the win-acme folder under C:\ProgramData\win-acme;
  • Open a browser on the host and navigate to https://win-192bg93tj8o.paul-lab.com:50443/swagger/index.html where win-192bg93tj8o.paul-lab.com is the vSEC:CMS server host name and 50443 is the port configured in vSEC:CMS under Options - Connections - ACME Service. If the communication is correct you should see something similar to below: 

Untitled.png