========================= ACME Service Introduction ========================= This guide, along with the specific configuration information for your account (provided by your Support contact) should help you configure ACMEv2 clients to connect to our service, request new certificates, and perform certificate renewal automatically. If you can't find what you're looking for, please drop a note to support@venafi.com or contact your account representative for assistance. ACME Clients ============= Prerequisites =============== To begin configuring an ACME client for use with ACM, you'll need to have the following prerequisites: 1. One or more Requestor roles added to your account. See https://help.ztpki.venafi.com/html/users.html for more information. 2. The Requestor needs to have API keys available during the configuration. You can get more information on this process at https://help.ztpki.venafi.com/html/manageapikeys.html. 3. The Certificate Policy in your account that will be used for certificate issuance must be enabled for ACME and you'll need the Certificate Policy ID. The Support team will provide a list of ACME-enabled Policy ID's to you. ================ ACME V2 Clients ================ The ZTPKI ACME API requires an ACME V2 client that support External Account Binding (EAB) - see https://tools.ietf.org/html/rfc8555#section-7.3.4. The clients listed here have all been tested with our service. +--------------------+-------------------------------------+------------+ | **Client** | **URL** |**Version** | +--------------------+-------------------------------------+------------+ | CertBot | https://certbot.eff.org | v. 5.3.4 | +--------------------+-------------------------------------+------------+ | Certify the Web | https://certifytheweb.com | v. 0.32.0+ | +--------------------+-------------------------------------+------------+ | Lego | https://go-acme.github.io/lego | v. 2.0.0+ | +--------------------+-------------------------------------+------------+ | Acme4j | https://shredzone.org/maven/acme4j | v. 2.5+ | +--------------------+-------------------------------------+------------+ ZTPKI recommends the Certbot ACME V2 client for Linux/macOS clients as it has had the most extensive testing by our developers. The certbot-auto script is recommended as it installs all required dependencies and keeps the Certbot client up to date. For Windows, the Certify the Web client provides an easy-to-use GUI and will manage the automatic binding of certs in IIS. The Lego client works quite well for command line applications but does not provide the IIS binding automation. It also works well on Linux, but doesn't have the direct integration with application servers to restart, etc. as Certbot does. If building Lego is an issue, ZTPKI can provide pre-built binaries for Windows, etc. ================================ ACME Client Configuration Info ================================ The following information is needed when configuring an ACME Client to work with the ZTPKI ACME API: **Server- ACME Directory Resource URI:** https://ztpki.venafi.com/acme//directory **Certificate Type:** This is the Certificate Policy ID provided to you by ZTPKI. It replaces the "" in the above URI. **EAB Key ID:** This is the API Key Identifier for External Account Binding. An existing ZTPKI HAWK REST API ID can be used (or a new one created specific for ACME). **EAB HMAC Key:** This is the API Key for External Account Binding. An existing ZTPKI HAWK REST API key can be used (or a new one created specific for ACME). .. warning:: Please note that the "EAB Key ID" and "EAB HMAC Key" should be treated as secrets and preferably not in plain text with persistent storage. Anyone with access to the EAB Key ID and EAB HMAC Key can setup new ACME accounts and request certificates through any certificate policy enabled in the ZTPKI REST API. The EAB Key ID and HMAC Key are needed for the creation of the ACME account and linking to your existing ZTPKI ACM account. Any further requests, renewals or revocations do not require access to these values. ======================= Certbot Configuration ======================= Installation ============= For Certbot software downloads and customized installation instructions for all supported platforms visit the Certbot website at https://certbot.eff.org/. Running Certbot ================ The following example shows the full CertBot command for retrieving a certificate from ZTPKI and installing into Apache: .. code-block:: RST certbot run --server https://ztpki.venafi.com/acme//directory --agree-tos --no-eff-email --apache --redirect --email --eab-kid --eab-hmac-key --domains www1.example.org,www2.example.org Here's an example in Ubuntu 20.04: .. code-block:: RST sudo certbot run --server https://ztpki.venafi.com/acme/certpolicyid/directory --agree-tos --no-eff-email --apache --redirect --email acmetest@hyid.com --eab-kid xxxxxxxxxxxx --eab-hmac-key xxxxxxxxxxxxxxxxx --domains acmetest.1234.venafi.com Saving debug log to /var/log/letsencrypt/letsencrypt.log Plugins selected: Authenticator apache, Installer apache Account registered. Requesting a certificate for acmetest.1234.venafi.com Performing the following challenges: http-01 challenge for acmetest.1234.venafi.com Enabled Apache rewrite module Waiting for verification... Cleaning up challenges Created an SSL vhost at /etc/apache2/sites-available/acmetest.1234.venafi.com-le-ssl.conf Enabled Apache socache_shmcb module Enabled Apache ssl module Deploying Certificate to VirtualHost /etc/apache2/sites-available/acmetest.1234.venafi.com-le-ssl.conf Enabling available site: /etc/apache2/sites-available/acmetest.1234.venafi.com-le-ssl.conf Enabled Apache rewrite module Redirecting vhost in /etc/apache2/sites-enabled/acmetest.1234.venafi.com.conf to ssl vhost in /etc/apache2/sites-available/acmetest.1234.venafi.com-le-ssl.conf - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Congratulations! You have successfully enabled https://acmetest.1234.venafi.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - IMPORTANT NOTES: - Congratulations! Your certificate and chain have been saved at: /etc/letsencrypt/live/acmetest.1234.venafi.com/fullchain.pem Your key file has been saved at: /etc/letsencrypt/live/acmetest.1234.venafi.com/privkey.pem Your certificate will expire on 2022-04-02. To obtain a new or tweaked version of this certificate in the future, simply run certbot again with the "certonly" option. To non-interactively renew *all* of your certificates, run "certbot renew" Renewal ========= The following example shows a renewal. The "--force-renewal" option can be added if the certificate is not near expiration. The "--server" option is not needed as the values are read from the "/etc/letsencrypt/renewal" directory: .. code-block:: RST certbot renew Many popular Linux distributions include automated renewals when using the Certbot packages available via their package manager. More information is available at https://certbot.eff.org/docs/using.html#renewing-certificates. Revocation =========== The following example shows a revocation: .. code-block:: RST certbot revoke --server https://ztpki.venafi.com/acme//directory --reason keycompromise .. warning:: It is highly recommended to at least specify the "server" in the global configuration file at "/etc/letsencrypt/cli.ini". Please note that it is **NOT** recommended to store the "eab-kid" and "eab-hmac-key" keys in any persistent storage - these keys can be used to request certificates from any certificate policy setup in the REST API. ============================== Certify the Web configuration ============================== Client Installation and Configuration ====================================== Once you have the Certify installation software downloaded, double-click the Installer to begin. You can take all the default values or customize the installation path as required in your environment. .. image:: ZTPKIScreenshots/AcceptAgreement.png .. image:: ZTPKIScreenshots/SelectLocation.png .. image:: ZTPKIScreenshots/SetupComplete.png The installation will complete and load the configuration screen: .. image:: ZTPKIScreenshots/CertifyMain.png You'll need to enable the use of custom Certificate Authorities. Click on Settings: .. image:: ZTPKIScreenshots/CertifySettings.png Then click UI Settings: .. image:: ZTPKIScreenshots/CertifyUISettings.png Click the "Certificate Authority Editor" box to enable this feature. Your selection will be saved automatically. .. image:: ZTPKIScreenshots/EnableCustomAuthorities.png Click on the Certificate Authorities link: .. image:: ZTPKIScreenshots/CertAuthoritiesLink.png Click on the Edit Certificate Authorities button to begin adding the ZTPKI CA information: .. image:: ZTPKIScreenshots/EditCertAuthorities.png On the Edit Certificate Authority screen, leave "(New Certificate Authority)" for the first drop-down menu. For Title, enter "My ZTPKI CA". For Production API, enter the Production ACME URL provided to you by ZTPKI. Leave the Staging API field blank. For Features, enable the following then click Save: .. image:: ZTPKIScreenshots/CAFeatures.png The next step is to register your account. First, select the My ZTPKI CA in the Preferred Certificate Authority drop-down list. Second, click New Account: .. image:: ZTPKIScreenshots/AddAccount.png Enter in your email address and click the "Yes, I agree" checkbox. .. image:: ZTPKIScreenshots/AddAccount.png Click the Advanced menu link. .. image:: ZTPKIScreenshots/EditCertAuthority_Advanced.png Enter in your API Key Id and Key (HMAC) values in the fields below and click "Register Contact" to complete the registration process. This is the only time that the API keys will be used. All future requests will use an authorization token stored on the host computer as protected data by Windows. .. image:: ZTPKIScreenshots/RegisterContact.png If you receive any errors, double-check your Id and Key information and try again. Contact ZTPKI Support if you are unable to complete this step. Requesting a New Certificate ============================== To start the new certificate request, click the New Certificate button: .. image:: ZTPKIScreenshots/NewCertificate.png Enter a name for this certificate request: .. image:: ZTPKIScreenshots/CertName.png Finish configuring the request- for 1), choose the Default Web Site or the site name from the Select Site drop-down list; for 2), select which domains to include in the certificate and which domain will be the Primary (appear in the Common Name field and first SAN field). The last step is to click the Save button. .. image:: ZTPKIScreenshots/CertOptions.png To test your certificate request configuration, click the Test button. .. image:: ZTPKIScreenshots/TestCert.png Resolve any errors as needed until the test is successful. .. image:: ZTPKIScreenshots/TestComplete.png To process the request, click Request Certificate: .. image:: ZTPKIScreenshots/RequestCert.png The new certificate will be requested and automatically installed in IIS. .. image:: ZTPKIScreenshots/RequestSuccessful.png Confirm the installation in IIS by viewing the Bindings screen in IIS Manager. .. image:: ZTPKIScreenshots/IISConfig.png Automatic Certificate Renewal ============================== The Certify the Web client installs a service running under the Local System account to check the status of existing certificates and submit renewal requests without administrator intervention. .. image:: ZTPKIScreenshots/ServiceAccount.png The Certify the Web client is configured to renew certificates within 30 days of expiration. This setting can be changed by going to Settings, then clicking Renewal Settings. .. image:: ZTPKIScreenshots/RenewalSettings.png For more information on the features of the Certify the Web client please visit their website at https://certifytheweb.com.