Using win-acme with ACME on EJBCA

Solution overview

ACME (Automatic Certificate Management Environment) is a protocol used to automate the process of issuing, renewing, and managing digital certificates. It enables servers and certificate authorities to communicate securely, allowing website owners to prove domain control and obtain trusted TLS certificates without manual intervention. This automation simplifies deploying HTTPS, improving security by ensuring certificates are always up to date.

Keyfactor’s EJBCA PKI can serve as a Registration Authority (RA) that supports the ACME protocol and full Certbot compatibility. This guide provides instructions on how to:

• Configure EJBCA profiles (end entity and certificate) to serve Certbot compliant certificates.
• Configure EJBCA as an ACME server to process requests from Certbot.
• Install and configure Certbot on Linux machines to get certificates from EJBCA via the ACME protocol.

The ACME (Automatic Certificate Management Environment) protocol is used to automatically prove control over a domain so that a certificate authority can issue a trusted certificate. To validate ownership, ACME defines different types of “challenges.” A challenge is essentially a test that the certificate authority asks you to complete, demonstrating that you really control the domain name you are requesting a certificate for. The most common challenges are http-01, dns-01, and tls-alpn-01.

• In the http-01 challenge, the ACME client, like Certbot, creates a special file with a unique token in a well-known location on your web server. The certificate authority then makes an HTTP request to http://yourdomain/.well-known/acme-challenge/<token> to retrieve and verify the file. If the server responds correctly with the expected contents, it proves that you control the web server for the domain.
• The dns-01 challenge works differently. Instead of serving a file over HTTP, a special DNS TXT record is created under your domain containing a unique token. The EJBCA queries the DNS records and verifies that the TXT record is present with the correct value. For automation, this requires creating scripts to automate the DNS record, and is more problematic.
• The tls-alpn-01 challenge uses a dedicated TLS handshake to prove control. In this method, the server must respond to a connection on port 443 with a specific TLS certificate extension containing the validation token. This approach is a bit more advanced and requires precise server configuration.

Among all three, automating with Certbot is easiest using http-01, because Certbot can automatically create and remove the challenge file on your web server without needing DNS access or special TLS configuration. This example explains how to set up this challenge-response.

Prerequisites

System prerequisites

This guide assumes the following:

• EJBCA is installed and has a PKI chain (root, policy, issuing, etc. CAs are configured).
• The user has administration capabilities on EJBCA for:
  • Registration Authority configuration
  • System configuration
  • End entity profile creation
  • Certificate profile creation

• The user has Administrator privileges on the Windows Server.
• IIS is configured on the Windows Server.

Diagrams

Following is a typical diagram showing the use case.

The Linux server has an application that uses PEM files for its certificate and keys. Examples are web servers (nginx, Apache Tomcat, etc.), e-mail servers (Postfix, Dovecot, Sendmail, etc.), VPN servers (OpenVPN, strongSwan).

Certbot is installed on the server, and configured to serve files to a specific directory. The application is then configured to consume those files. In this example, we will configure an nginx web server to use the files that certbot generates.

Since this example is a web server, it references the http-01 challenge type.

Procedure

This section covers the process to use win-acme with ACME on EJBCA.

EJBCA setup

Step 1: Configure certificate profile

1. Log in to your management CA’s AdminWeb.
2. Select CA Functions > Certificate Profiles.
   
   The Manage Certificate Profiles page displays a list of available profiles.
3. Click Clone next to the SERVER template to use that as a basis for creating your new profile.
4. Name the new certificate profile, and then click Create from template.
5. On the Edit page, verify that the type is End Entity and update the following:
   • For Signature Algorithm, verify that Inherit from Issuing CA is selected.
   • For Validity or end date of the certificate, specify 47d for 47-day certs.
   • For Expiration Restrictions, only allow certificates to expire on Tuesdays, Wednesdays, and Thursdays to avoid certificates expiring close to a weekend.
6. Under Permissions, make sure the following items are checked.
   • Allow Subject DN Override by End Entity Information
   • Use Certificate Storage
   • Store Certificate Data
7. The X.509v3 extensions section allows you to define the extensions added to the certificate.
   • For Key Usage, verify that Digital Signature and Key encipherment are the only items selected.
   • For Extended Key Usage, verify that Server Authentication is selected.
   • For X.509v3 extensions - Names, verify that Subject Alternative Name is selected and clear the Issuer Alternative Name.
   • Under X.509v3 extensions - Validation data:
     • Enable CRL Distribution Points to allow validation later on.
     • Enable Use CA defined CRL Distribution Point to use the value preconfigured in the CA.
     • Enable Authority Information Access to use the locations configured in your CA settings.
       • Enable Use CA defined OCSP locator for where the OCSP services are available.
       • Enable Use CA defined CA issuer for where the issuing CA certificate can be retrieved from.
8. Under Other Data, update the following:
   • Clear LDAP DN order to disable the LDAP ordering of the DN attributes and use the standard X.509 ordering instead.
   • For Available CAs, select the Issuing CA that is associated with ACME requests.
9. Click Save to store the certificate profile.

Step 2: Configure end entity profile

1. Select RA Functions > End Entity Profiles to view a list of all certificate profiles.
2. In the Add Profile field, add a name for the new profile, and then click Add profile.
3. Select the newly created profile, and then click Edit End Entity Profile to update the profile.
4. Verify or update the following items.
   1. For Type select Default.
   2. For Batch generation (clear text pwd storage) make sure Use… is checked.
   3. For End Entity E-Mail make sure:
      1. Use… is checked.
      2. Required is unchecked.
      3. Modifiable is checked.
5. For the Subject CN Attributes, verify that CN, Common Name is Required and Modifiable.
   • The default CSR that Certbot creates only uses the CN attribute. If any other attributes are required, we can have EJBCA add them to the certificate. To implement this, select the attribute you want to use (for example O, Organization), and then click Add.
   • Make sure both Required and Modifiable are unchecked and that the box has a default value entered (for example, Keyfactor).
6. For the Other Subject Attributes, make sure that DNS Name is showing and that only Modifiable is checked.
7. For Main Certificate Data, make sure that:
   1. The Default Certificate Profile and the Available Certificate Profiles have only the certificate profile created above selected.
   2. The Default CA and the Available CAs have only the Issuing ACME CA selected.
   3. The Default Token and the Available Tokens only have User Generated selected, as Certbot is sending a PKCS#10 (CSR) request to EJBCA.
8. Click the Save button at the bottom of the page to save the end entity profile.

Step 3: Configure ACME alias/endpoint

1. In EJBCA, select System Configuration > ACME Configuration to manage the ACME Aliases. In EJBCA, multiple ACME aliases can be created for different use cases. Each alias is tied to an end entity profile.
2. Under List of ACME Aliases, click Add.
3. On the configuration screen, add or update the following.
   • For Name, enter the name to use for the endpoint. This name is used to call this endpoint via /ejbca/acme/<name>/directory. For example, if your server is located at ejbca.example.com, then the URL for an endpoint named my-acme would be:  
     https://ejbca.example.com/ejbca/acme/my-acme/directory.

   • For RA Name Generation Scheme, use the radio button to select the end entity name that the endpoint generates when fulfilling an ACME certificate request select DN.

     DN takes a part of the PKCS#10 (CSR) subject and creates the end entity username from that. CN (Common Name) is already selected; therefore. only select the DN radio button.

   • For End Entity Profile, select the profile created above.
   • For DNS identifier challenge types, select http-01. (Refer to the Solution overview for more information about this selection).
   • Require client approval for Terms of Service changes should be unchecked to ease automation efforts.
   • Agree to new Terms of Service allowed should be checked to ease automation.
   • All other fields can remain the default.
4. Click Save to save the alias to EJBCA.

Step 4: Enable the ACME protocol in EJBCA

1. In EJBCA, select System Configuration > System Configuration > Protocol Configuration to get to the list of protocols enabled in EJBCA.
2. For the ACME row, make sure Status is Enabled. If it isn’t, click the Enable button.

Windows setup for win-acme

Step 1: Update the Windows trust store

The Windows machine must trust the EJBCA endpoint. To do this, we must update the trust store on the machine.

1. Download the Management CA certificate from EJBCA.
   1. Log in to the EJBCA RA Web interface by navigating to the https://<ra-url>/ejbca/ra/ page.
   2. At the top of the page, select CA Certificates and CRLs.
   3. Under the Certificate column, select PEM for the row associated with your EJBCA’s management CA.
   4. Rename the file to end in .crt for compatability.
2. Copy the file to the Windows machine.
3. Install the certificate on the machine.
   1. Double-click the .crt file.
   2. Click the Install Certificate… button.
   3. Select the Local Machine radio button
   4. Click the Next button.
   5. Select the Place all certificates in the following store radio button.
   6. Click the Browse… button.
   7. Select the Trusted Root Certification Authorities folder.
   8. Click the OK button.
   9. Click the Next button.
   10. Wait until you see confirmation that the certificate has been added.

Step 2: Download and install win-acme

Perform the following to download and install win-acme from the website.

1. Run Windows PowerShell as an Administrator.

2. Create a target directory.

   mkdir 'C:\Program Files\win-acme'
   cd 'C:\Program Files\win-acme'

3. Download the latest win-acme zip file from https://win-acme.com/.
   • Copy the URL for the latest recommended version.
     

   • Copy this to the directory above (or use curl to download it).

     curl -o 'win-acme.zip' https://github.com/win-acme/win-acme/releases/download/<version>/win-acme.<version>.x64.trimmed.zip

4. Unzip the file.

   Expand-Archive -Path ".\win-acme.zip" -DestinationPath ".\"
   del win-acme.zip

Step 3: Determine your website binding

IIS has a default binding of blank. This means that any traffic on http (port 80) gets a response. To check your binding configuration:

1. Open Server Manager > Tools > Internet Information Services (IIS) Manager.
2. On the left-hand side, click the > next to your server’s name to expand it.
3. Now expand the Sites folder by clicking the > next to it.
4. Click the web site you are going to manage (on most new setups, this is the Default Web Site).
5. On the right-hand side of the IIS Manager, under the Edit Site area, select Bindings….
   • If the Host Name column for http is blank, then you have a binding that matches all host headers on that IP and port. This is normal for the Default Web Site.
   • If the Host Name column has a value, then you have a host-specific binding and only requests matching that Host header will be served by this site.

Step 4: Run win-acme to get a certificate

Win-acme is run with a set of commands to tell it what to do. Following is a summary of the ones required for using EJBCA to get a certificate.

Option 1: Running win-acme in interactive mode

The simplest way to run win-acme for the first time is to run it in interactive mode. In this case, the only thing we need to do is feed in the baseuri switch.

cd 'C:\Program Files\win-acme'

.\wacs.exe --baseuri "https://<ejbca-endpoint>/ejbca/acme/<alias>/directory"

For example, for ejbca.example.com and the alias acme-http, this becomes:

.\wacs.exe `
--baseuri "https://ejbca.example.com/ejbca/acme/acme-http/directory"

You are then prompted through the generation process.

Win-acme then walks you through the process of getting an initial certificate for your web site. This starts with a screen similar to the following:

If you haven’t bound your website to a specific hostname, then you must select the M: Create certificate (full options) option.

Walking through the example above, we perform the following steps to issue a certificate for a single website located in the Default Web Site.

1. Type M and then <enter>.
2. Type 2 and then <enter> to manually input the hostname.
3. At the host: prompt, type your web site’s URL. For example, www.example.com.
4. Press the <enter> key to accept the default friendly name.
5. Press the <enter> key to select a Single Certificate.
6. Press the <enter> key to use the default http-01 challenge and serve the files from memory.
7. Press the <enter> key to use an RSA/2048 key.
8. Press the <enter> key to use the Windows Certificate Store (Local Computer) to store the key and certificate into.
9. Press the <enter> key to use the default configuration of WebHosting.
10. Press the <enter> key to move on: No (additional) store steps.
11. Press the <enter> key to have win-acme bind the certificate to port 443, also known as Create or update bindings in IIS.
12. Type 1 to select the Default Web Site, and then press the <enter> key.
13. Press the <enter> key to move on.
14. When prompted, type y, and then press <enter> to agree to the Terms of Service.

15. Once the process is finished successfully, you should see something that looks like the following.

    A simple Windows ACMEv2 client (WACS)
     Software version 2.2.9.1701 (release, trimmed, standalone, 64-bit)
     Connecting to https://ejbca.example.com/ejbca/acme/acme-http/directory...
     Connection OK!
     Scheduled task not configured yet
     Please report issues at https://github.com/win-acme/win-acme
     Running in mode: Unattended
     Source generated using plugin Manual: www.example.com
    Terms of service:    C:\ProgramData\win-acme\ejbca.example.comejbcaacmeacme-httpdirectory\terms
     Plugin Manual generated source www.example.com with 1 identifiers
     Plugin Single created 1 order
     [win-47.keyfactoriot.com] Authorizing...
     [win-47.keyfactoriot.com] Authorizing using http-01 validation (SelfHosting)
     [win-47.keyfactoriot.com] Authorization result: valid
     Downloading certificate [Manual] www.example.com
     Store with CertificateStore...
     Installing certificate in the certificate store
     Adding certificate [Manual] www.example.com @ 2025/7/8 in store WebHosting
     Adding certificate CN=EXAMPLE ISSUING RSA L1, OU=IoT, O=Keyfactor, C=US in store CA
     Adding certificate CN=EXAMPLE ROOT RSA X1, OU=IoT, O=Keyfactor, C=US in store CA
     Installing with IIS...
     Adding new https binding *:443:
     Committing 1 https binding changes to IIS while updating site 1
     Adding Task Scheduler entry with the following settings
     - Name win-acme renew (ejbca.example.comejbcaacmeacme-httpdirectory)
     - Path C:\Program Files\win-acme
     - Command wacs.exe --renew --baseuri "https://ejbca.example.com/ejbca/acme/acme-http/directory"
     - Start at 09:00:00
     - Random delay 04:00:00
     - Time limit 02:00:00
     Adding renewal for [Manual] www.example.com
     Next renewal due after 2025/9/1
     Certificate [Manual] www.example.com created
     N: Create certificate (default settings)
     M: Create certificate (full options)
     R: Run renewals (0 currently due)
     A: Manage renewals (1 total)
     O: More options...
     Q: Quit
     Please choose from the menu:

16. Type Q, and then press the <enter> key to exit win-acme.

Win-acme will automatically renew the certificate as it comes up for renewal.

Option 2: Running win-acme in non-interactive mode

The process in option 1 is manual, but not very scalable for large deployments. To accommodate this, win-acme can run through the entire process above without any user input if additional switches are used. To simulate the above manual process, we run the following.

cd 'C:\Program Files\win-acme'

./wacs.exe --target manual `
  --host <URL-to-get-certificate-for> `
  --store certificatestore `
  --installation iis `
  --installationsiteid 1 `
  --accepttos `
  --emailaddress <admin-email-address> `
  --baseuri https://<ejbca-ra-url>/ejbca/acme/<alias>/directory

For example, for the www.example.com website ejbca.example.com and the alias acme-http, this becomes:

./wacs.exe --target manual `
  --host www.example.com `
  --store certificatestore `
  --installation iis `
  --installationsiteid 1 `
  --accepttos `
  --emailaddress admin@example.com `
  --baseuri https://ejbca.example.com/ejbca/acme/acme-http/directory

The output is similar to the example above.

Verify configuration

For a web server, the simplest verification is to navigate the the web site and prove that the connection is trusted!