Sectigo Java Agent

Overview

The Sectigo Java Agent is a tool created as an executable file to provide a secure automation solution for managing Sectigo SSL/TLS certificates to protect TLS communication on Java servers. The current version of the agent is designed as a standalone solution to provide certificate management for SSL/TLS certificates that should be manually imported to the Java KeyStore and CACert store on the Java server.

The agent can obtain the following types of SSL/TLS certificates:

  • Domain Validation (DV)

  • Organization Validation (OV)

  • Extended Validation (EV) certificates

Scope

This guide covers instructions on connecting to the Sectigo ACME or REST APIs servers and enrolling or renewing certificates. Importing the enrolled certificates to a keystore is outside the scope of this guide.

Audience

This guide is intended for IT administrators and system administrators who have knowledge of IT security, cloud security, and are also familiar with Sectigo Certificate Manager (SCM).

Architecture

Sectigo Java Agent architecture

The agent is capable of working both with ACME and REST API servers.

The REST implementation uses two Sectigo REST APIs to enroll and renew SSL certificates:

  • OAuth API: This API is responsible for OAuth authentication and JWT token creation.

  • Enrollment API: This API is responsible for certificate management (enrollment and renewal) using access token received from the OAuth API. The enrollment API supports OAuth 2.0 to protect customer information.

The following key types are supported: RSA-2048, RSA-3072, RSA-4096, and ECDSA-256.

The agent supports only the pre-validated domains in Sectigo Certificate Manager (SCM). The domains for which certificates are requested should go through Domain Control Validation (DCV) in SCM as per the instructions provided in Section 6.4.2 How To Validate Domains of the SCM administrator’s guide. For more information on DCV methods, see Domain Control Validation Methods in Sectigo’s Knowledge Base.

Execution workflow

During execution, the agent does the following:

  1. Reads the certificates.yml file(s) in the domains directory and its subdirectories (if any) to get the CSR filename(s) and other certificate enrollment information. If you have multiple CSR files and an error occurs while reading one of them (for example, the file is not found), the tool ignores that file and proceeds to the next.

  2. Sends the CSR with an enrollment request to SCM.

  3. Downloads the public certificate (.crt) and certificate ID (.ids) files to the directory that hosts certificates.yml. The entire certificate chain is downloaded from SCM: a common file (which includes the root CA, issuing CA, and server (leaf) certificates), and the same certificates presented as three separate files. Additionally, the server certificate and its chain are converted to a .pem file.

The configuration information can be stored in plaintext or encrypted form.

Package contents

The package contains the following components:

  • domains: This folder contains the certificate.yml file, CSRs, and provisioned certificates. You can change the folder name or location for these files using the directory parameter in the config.yml file.

    • certificates.yml: This file contains information for enrolling certificates, such CSR filenames, renewal window, and more. The certificates.yml file and your CSR can reside in the domains root folder or you can place them in subfolders for specific domains.

  • config.yml: This files stores the secrets and configuration

  • SCM Client EULA v1.0.1.txt: The EULA agreement. You need to accept it once when running sectigo-java-agent for the first time.

  • sectigo-java-agent: The agent as an executable file

Prerequisites

The following prerequisites must be met before running the agent:

  • Client machine: A client machine to run the script and store the provisioned certificates

  • Operating system: Linux. The tool was tested on RHEL 8, Debian 11, and Ubuntu 20.04

  • CSR file: Generate a CSR for a certificate and place it in the domains directory or its subdirectories for specific domains.

Initial setup

Installation instructions

To unzip the package and configure permissions for a non-root user:

  1. (Optional) Create a non-root user that has access to the /home/user/sectigo directory:

    1. Create a group called sectigogroup.

      sudo groupadd sectigogroup
    2. Create a sectigouser user, add them to the sectigogroup group, and set /home/user as the home directory for the user.

      sudo useradd -s /bin/false -g sectigogroup -d /home/user sectigouser
    3. Switch to the newly created user.

      su sectigouser
  2. Download the sectigo-java-agent.zip file to a local folder on a Linux machine.

  3. Create a new directory called sectigo somewhere on your machine. The following commands assume that the directory is located in /home/user.

  4. Extract the contents of the sectigo-java-agent.zip archive to the /home/user/sectigo.

    unzip ./sectigo-java-agent.zip

Set up the config file

The agent can work with plaintext or encrypted credentials to obtain OAuth 2.0 credentials and other information, depending on the selected protocol. To reduce the amount of manual, error-prone configuration, particularly for encryption, the agent offers a prompt where you can type answers on the command line to specify the protocol, credentials, and whether to encrypt the credentials. The values you enter are added to the config.yml file.

For more information about using the agent, run sectigo-java-agent --help.

  • ACME

  • REST

To set up the configuration file for use with ACME protocol:

  1. Obtain and make a note of the External Account binding (EAB) information (ACME URL, key ID, and HMAC key):

    1. Log in to SCM at https://cert-manager.com/customer/<customer_uri> with your credentials.

    2. Expand the left pane and navigate to Enrollment > ACME.

    3. On the ACME page, select your ACME URL, and click Accounts.

    4. Select your account and click Details.

      EAB details
  2. Run the agent with the --configure option and follow the prompt to provide ACME credentials, logging level, and certificate directory. If you choose to encrypt your credentials, this command also creates a key pair in the current directory and encrypts your HMAC key using the public key.

    sectigo-java-agent --configure

    At each prompt, provide the parameters that will define your configuration file. The square brackets indicate an existing or default value, if any.

    Please specify your Sectigo API parameters parameters for the configuration file.
    Sectigo API Type (1 - Enrollment, 2 - ACME): 2
    Sectigo ACME URL [None]: <https://acme.demo.sectigo.com>
    Sectigo ACME Key ID [None]: <2a82af7331a11fc8b9ec2793d924b0aa>
    Sectigo ACME HMAC Key [None]: <AqlqlXB9mQoQzrGHmFzLSdbhENiea9RibwyCZoNfXrp7o7A1Yb9pvPwCPFpl7ZBMztc752le8VhCDXyTg5ms68U6>
    Encrypt ACME HMAC Key (yes / no) [yes]: <yes>
    Log level (panic, fatal, error, warning, info, debug, trace) [trace]: <trace>
    Certificate database directory [./domains]: <./domains>
    Configuration file successfully created!
    Run the agent with the following command.
    ./sectigo-java-agent

    When you are prompted for the logging level, the possible values are:

    • trace: Logs all events. The default value.

    • debug: Logs events like enrolling a certificate (less detailed logs than with trace)

    • info: Logs only events like certificate renewal

    • fatal: Logs only fatal errors

    • error: Logs all errors

    • warning: Logs only warnings

    The logs will be stored in the logs directory within the working directory.

An example configuration file (config.yml)
sectigo:
  acme:
    apiUrl: "https://acme.demo.sectigo.com"
    kid: "2a82af7331a11fc8b9ec2793d924b0aa"
    hmacKey: "4Of1p44zWexJ1lUQcQmozXyisMHEBAGwKOm7V6hqOon+CcpZfudSSXl58shivtyM/GcR1KTm8tjeqPXYcmhcRs0yFjcJSdNtvs7MCso2EotOneAwDLFf7LzshNtMm+vDUP8di1JntaLevRjRiG4m2exUTvxwVQI8NYksizHAp7NdkpsyxOC01Tp2tdZ0Pny4/hI1PL9a2i/9I/l5i7GYm3QOjsARoBSAuCfaN7ntHTN2yrLQEdSBHGeoOTBMUNJBpTcnOv2MGnvFeTivFIRISNO3jJmMwOPrFqdNrM7xux3+lLnAvQn2aECPw4SA5zWj0vwKXRy913LajcVH4NJ06Q=="
  logger:
    level: trace
  certificate:
    database:
      directory: ./domains
  encrypted: rsa_key.pri

To set up the configuration file for use with REST protocol:

  1. Enable API access for your account:

    1. Log in to SCM at https://cert-manager.com/customer/<customer_uri> with your credentials.

    2. On the Organizations page, select your organization and click Edit.

    3. Select Certificate Settings, then expand the SSL Certificates menu.

    4. Enable the Web API option.

      If the option is not available for your account, contact Sectigo Support or the Onboarding Team to have SCM API access enabled.
  2. Obtain and make a note of the API URL, client ID, and client secret values in SCM:

    1. Select Enrollment  REST. Under URL next to SSL Certificates REST API, you will see the API URL. You only need the base URL, such as https://scmqa.enroll.demo.sectigo.com.

      SSL certificates REST API
    2. Select SSL Certificates REST API and click Accounts.

    3. Select your account and click Edit.

      SSL certificates REST accounts
    4. Click Reset Secret and confirm client reset secret.

      SSL certificates REST accounts

      You will see the client ID and client secret.

      Client ID and secret
  3. Run the agent with the --configure option and follow the prompt to provide REST API credentials, logging level, and certificate directory. If you choose to encrypt your credentials, this command also creates a key pair in the current directory and encrypts your client secret using the public key.

    sectigo-java-agent --configure

    At each prompt, provide the parameters that will define your configuration file. The square brackets indicate an existing or default value, if any.

    Please specify your Sectigo API parameters parameters for the configuration file.
    Sectigo API Type (1 - Enrollment, 2 - ACME): 1
    Sectigo Enrollment API URL [None]: <https://scmqa.enroll.demo.sectigo.com>
    Sectigo Client ID [None]: <b8923830-11f5-4c34-951b-fc1235634972>
    Sectigo Client Secret [None]: <Ti]hXzuxj.!T,zg!S0rZ0StbwyDlhCP4>
    Encrypt Client Secret (yes / no) [yes]: <yes>
    Log level (panic, fatal, error, warning, info, debug, trace) [trace]: <trace>
    Certificate database directory [./domains]: <./domains>
    Configuration file successfully created!
    Run the agent with the following command.
    ./sectigo-java-agent

    When you are prompted for the logging level, the possible values are:

    • trace: Logs all events. The default value.

    • debug: Logs events like enrolling a certificate (less detailed logs than with trace)

    • info: Logs only events like certificate renewal

    • fatal: Logs only fatal errors

    • error: Logs all errors

    • warning: Logs only warnings

    The logs will be stored in the logs directory within the working directory.

An example configuration file (config.yml)
sectigo:
  enrollment:
    apiUrl: "https://scmqa.enroll.demo.sectigo.com"
    clientID: "b8923830-11f5-4c34-951b-fc1235634972"
    clientSecret: "w2XiPAa3kdmAnnbQVebUwqBlh2hMX8g+Rq+fiVbUZFakWcDM/2H8iiPqvp86BghJYpCVFLXEHHNtdRxhYzxLR0l84iiV2mMdOT7LSk3mF8AnqQ8ESrEoEYpyrQGtX1eTdswFoF1tLLnXXc9NamSZuzKJdu0sSCKTcIQw+v89D4WyCyQ/NXSBlkpm2OC1ImxAY0VlByYQ8hCMKz62OuvKznq9TjZxGmfIznATh7wErXYvBOpX4mJi8kVV3EgfqNi9eSnSoP0WPd89QuqOg3Rqs0B+IZ41tRiBJjjcAh+ttdmeCys+rf+No6ALVcYejOEJZftOriWgi22Ii0xJj+ZNzA=="
  logger:
    level: trace
  certificate:
    database:
      directory: ./domains
  encrypted: rsa_key.pri

Set up the certificate file

The agent offers an automated way to configure parameters, such as the CSR filename or renewal window, in the certificates.yaml.

Before running the command, place one or more CSR files in the domains root directory or its subdirectories for specific domains.

sectigo-java-agent csr add -d </domains/my_domain> -f <csr-file-1>.csr -r <7> \
-m <"Certificate for Java keystore"> -s <domain.com, www.domain.com> -e <[email protected]>

The preceding command creates a certificates.yml file in the my_domain directory, and adds your values to the file. If you run the command again for another CSR stored in the same directory, the agent adds more entries to the existing certificates.yml file.

An example certificate configuration file.

sectigo:
  certificates:
    - comments: Certificate for Java keystore
      csr: csr-file-1.csr
      subjAltNames: ["example.com", "www.example.com"]
      externalRequester: "[email protected]"
      renewBeforeDays: 7
    - comments: Certificate for Java keystore
      csr: csr-file-2.csr
      subjAltNames: ["domain.com", "www.domain.com"]
      externalRequester: "[email protected]"
      renewBeforeDays: 10

To list all CSR files from the certificates.yml file, run sectigo-java-agent csr list. If you need to view CSR files that reside in a specific directory, run sectigo-java-agent csr list -d </domains/your_directory.

To remove a CSR from the certificates.yml file, run sectigo-java-agent csr remove -f <csr-file>.csr -d </domains>.

Using the agent

Enroll a certificate

sectigo-java-agent

For more information about the available options, run sectigo-java-agent --help.

Don’t remove the .csr and .ids files after enrolling a certificate. The agent uses the information herein to check the certificate’s expiration date and renew the certificate.

The filename of a provisioned certificate includes the CN and expiry date.

Provisioned certificates in working directory

These are the same certificates in SCM.

Provisioned certificates in SCM

You can view the details of a provisioned certificate by running sectigo cert info -f </domains/cert-file>.crt.

Provisioned certificate details

Import a certificate to a keystore/truststore

To add a certificate to a keystore or truststore using keytool, run the following command.

  • Keystore

  • Truststore

keytool -import -alias foo -file certificate.crt -storetype JKS \
-keystore mycerts.jks -storepass johndoe
keytool -import -alias foo -file certificate.crt -storetype cacerts \
-keystore mycerts.jks -storepass johndoe
The server certificate must be imported to a keystore (-storetype JKS), and the CA certificates must be imported to a truststore (-storetype cacerts).

Renew a certificate

Set the renewal period in the renewBeforeDays parameter of the certificates.yml file and run the agent.

The renewBeforeDays parameter doesn’t affect the renewal process for revoked certificates—​if the agent identifies a revoked certificate, it enrolls a new certificate using the information from the certificate configuration file.

You can also create a cronjob that will invoke the agent on a schedule to check the certificate expiry status:

  1. Run crontab -e on the terminal.

  2. Add a cronjob that will trigger the agent.

    The following example will trigger the agent every month.

    0 0 1 * * cd /home/ubuntu/sectigo-java-agent && ./sectigo-java-agent