Sectigo Client SDK for Java integration

Overview

The Sectigo Client SDK is a set of tools that allow you to easily communicate with APIs from Sectigo Certificate Manager (SCM) through your own custom application. The SDK exposes several endpoints that provide a solution for the enrollment, collection, renewal, replacement, and revocation of SSL/TLS and client certificates issued by SCM.

The SDK is distributed as a Java library featuring the following:

  • RSA 2048, 3072, and 4096-bit private key generation

  • Certificate signing request (CSR)

  • Unmanaged function endpoints which communicate with specific SCM APIs and return JSON responses:

    • EnrollCertificate, CollectCertificate, RenewCertificate, ReplaceCertificate, and RevokeCertificate

  • Managed function endpoints which provision communications with SCM and provide means for storing and managing certificate-related files locally:

    • RequestManagedCertificate and ReplaceManagedCertificate

Sectigo Java integration

Prerequisites

The Java library has the following prerequisite:

  • Java version 1.10

The Sectigo Client SDK for Java contains the following:

  • sectigo-jcert.jar: The SDK’s Java library to be included in your project

  • sample.java: Sample code that demonstrates end-to-end examples of enrollCertificate, collectCertificate, and requestManagedCertificate for SSL and client certificates

Java Sectigo integration package

The SDK structure

The SDK exposes functional endpoints that can be divided into the following categories:

  • Connection endpoint is used for configuring the SCM connection parameters. For more information, see Connection endpoint.

  • Unmanaged endpoints interact with specific SCM APIs directly and return a JSON response. These endpoints do not store and maintain files locally. For more information, see Unmanaged endpoints.

  • Managed endpoints provision communications with SCM APIs (a single managed endpoint can communicate with multiple SCM APIs). In addition to returning a JSON response, these endpoints store and manage certificate-related files locally. The certificate-related files consist of a private key (.key), a CSR (.csr), a certificate (.crt), and a certificate identifier (.ids). For more information, see Managed endpoints.

  • Utility endpoints are used for general functionality such as configuring the SDK’s logger. For more information, see Utility endpoints.

Endpoints

Each functional endpoint provides a set of methods.

Connection endpoint

Connection endpoint has the following method:

  • SetConnectionParameters(params): Sets the connection parameters that are required to interact with SCM using the managed and unmanaged endpoints.

Unmanaged endpoints

Unmanaged endpoints have the following methods:

  • EnrollCertificate(params, certCategory): Enrolls a certificate on SCM and returns the response object. Provides you with the means to generate a private key and a CSR which would then be included in the returned response.

  • CollectCertificate(params, certCategory): Collects a certificate from SCM and returns the response object.

  • RenewCertificate(params, certCategory): Renews a certificate on SCM and returns the response object.

  • ReplaceCertificate(params, certCategory): Replaces a certificate on SCM and returns the response object.

  • RevokeCertificate(params, certCategory): Revokes a certificate on SCM and return the response object.

Managed endpoints

Managed endpoints have the following methods:

  • RequestManagedCertificate(params, certCategory): Enrolls and collects a certificate from SCM. Stores and maintains the .key, .csr, .crt, and .ids files. Checks an existing certificate’s validity, auto-renews it if applicable, and updates certificate-related files accordingly. Provides you with the means to generate a private key and a CSR.

  • ReplaceManagedCertificate(params, certCategory): Replaces an existing certificate and updates certificate-related files accordingly.

Utility endpoints

Utility endpoints have the following methods:

  • WriteLog(message): Writes a log message on the library’s logger.

  • ConfigureLogger(params): Configures the library’s logger based on the parameters supplied by you

  • Params: A dictionary of parameters required for each function (Map<String, Object>--for example, <"sectigo_csr_key_size", 2048> or <"sectigo_auto_renew", true>)

  • certCategory: "ssl" or "client"

Response

The contents of response objects are based on functions that you call. The following table lists and describes all the possible variables that may be returned in a response object from a managed or unmanaged endpoint.

Response parameters File storage Without file storage

status

The status of the operation: SUCCESS or FAILURE

message

A message describing the result of the operation

category

Certificate category: SSL, Client

operation

The performed operation (Enroll, Replace, Renew, Revoke, Collect, RequestManagedCertificate, or ReplaceManagedCertificate)

ssl_id

sslId of an SSL certificate

order_number

orderNumber of a client certificate

certificate

Certificate file location and name

The certificate field is not shown, since it already appears under scmResponse.body.

csr

CSR file location and name

CSR in PEM format

private_key

Private Key file location and name

Private Key in PEM format

scm_response

Response received from the last REST call

timestamp

Time of the last operation

sub_operations

An array of suboperations that were executed as part of the managed endpoint. This field only applies to managed endpoints.

The certificate response field is only included in responses from managed endpoints.

The sub_operations response field is only included in responses from managed endpoints.

SCM response parameters

status

The status of the REST API call: SUCCESS or FAILURE

statusCode

HTTP status code received from the REST call

body

HTTP response’s body

For direct endpoints, the SCM response field is always included in the response if an interaction with SCM took place, regardless of whether the status of the request was SUCCESS or FAILURE.
Suboperation parameters

operation

Applicable suboperation (Enroll, Replace, Renew, Revoke, or Collect)

timestamp

HTTP response’s body

status

The status of the operation: SUCCESS or FAILURE

message

A message describing the result of the operation

Sample responses

Unmanaged API endpoints.

Java Sectigo unmanaged API endpoints

Managed API endpoints.

Java Sectigo managed API endpoints

Logging

The SDK includes a custom logger that supports the following:

  • Logs are always stored in a log file. You can customize the path for the log file using the logger parameters provided in the following table.

  • Logs can be sent to STDOUT. You can enable or disable the output to STDOUT using the logger parameters provided in the following table.

  • Logs are rotated based on a maximum file size (for example, 10 MB). You can configure the maximum file size and the maximum number of backed up log files using the logger parameters provided in the following table.

Parameter Description

sectigo_logger_file_path

The path where the logs should be stored. The default value is "log/<library_name>.log".

sectigo_logger_stdout_flag

A flag to determine whether logs are to be sent to STDOUT or not. The default value is true.

sectigo_logger_max_file_size

The maximum file size for the rotated logs. The default value is 10.

sectigo_logger_max_num_backups

The maximum number of backup files for the rotated logs. The default value is 10.

The SDK parameters

The SDK provides various parameters that you can use in different scenarios.

Customer-specific parameters

The following table lists parameters that are required for establishing a connection with SCM. These parameters are used by the connection endpoint via the SetConnectionParameters() method.

Parameter Type Description

sectigo_cm_user

Mandatory

User ID to access your URI

sectigo_cm_password

Mandatory

Password to access your URI

sectigo_cm_uri

Mandatory

Your specific URI

sectigo_cm_base_url

Mandatory

The base URL of the Sectigo Certificate Authority

CSR parameters

The following table lists parameters that are required for the generation and use of the CSR.

Parameter Type Description

sectigo_csr_domain

Conditional

Single value for a domain included in the certificate Common Name (CN) field. Required if sectigo_csr_subject is not provided.

sectigo_csr_subject

Conditional

CSR subject. If this parameter is provided, then you generate the default RSA 2048-bit private key to be used for the CSR. Required if the other parameters for the CSR have not been provided.

sectigo_csr_country

Conditional

The country name included in the certificate Country (C) field. Required if sectigo_csr_subject or sectigo_csr is not defined.

sectigo_csr_state

Conditional

The state or province name included in the certificate State (ST) field. Required if sectigo_csr_subject or sectigo_csr is not defined.

sectigo_csr_location

Conditional

The location name included in the certificate Location (L) field. Required if sectigo_csr_subject or sectigo_csr is not defined.

sectigo_csr_organization

Conditional

The organization name included in the certificate Organization (O) field. Required if sectigo_csr_subject or sectigo_csr is not defined.

sectigo_csr_organization_unit

Conditional

The organization unit included in the certificate Organization Unit (OU) field. Required if sectigo_csr_subject or sectigo_csr is not defined.

sectigo_csr_email_address

Conditional

The email address included in the certificate emailAddress field. Required if sectigo_csr_subject or sectigo_csr is not defined.

sectigo_csr

Conditional

The full path of the CSR file. If provided, then the subject parameters are ignored.

sectigo_csr_key_algo

Optional

The private key algorithm to use to generate the private key. The default value is RSA.

sectigo_csr_key_size

Optional

Size of the TLS/SSL key to generate. Possible values:

  • 2048-bit (default)

  • 3072-bit

  • 4096-bit

Unmanaged API endpoint parameters

Defining unmanaged endpoint parameters allows you to configure certificate enrollment, collection, renewal, replacement, and revocation.

EnrollCertificate

The following table lists parameters that are used for enrolling a certificate.

Parameter Type Description

SSL certificates

sectigo_cm_org_id

Mandatory

Your organization ID (numeric)

sectigo_ssl_cert_type

Mandatory

The type of SSL certificate (numeric). This is the ID of the SSL certificate type.

sectigo_ssl_cert_validity

Mandatory

The certificate validity period in days (numeric). The values available are dependent on the selected sectigo_ssl_cert_type.

sectigo_ssl_cert_external_requester

Optional

A comma-separated list of emails

sectigo_ssl_cert_comments

Optional

Comments for certificate enrollment

sectigo_ssl_cert_num_servers

Conditional

The number of server licenses (numeric)

sectigo_ssl_cert_server_type

Optional

The server type ID (numeric)

sectigo_ssl_cert_subject_alt_names

Optional

A comma-separated list of subject alternative names (SAN)

sectigo_ssl_cert_custom_fields

Optional

Custom fields to be applied to the requested certificate. The expected format for custom fields is [{"name":"custom_field_1","value":"value_1"},{"name":"custom_field_2","value":"value_2 "}]. If you are providing this input in a JSON string, ensure that the internal double quotes are escaped properly using \.

Client Certificates

sectigo_cm_org_id

Mandatory

Your organization ID (numeric)

sectigo_client_cert_type

Mandatory

The type of client certificate (numeric). This is the ID of the client certificate type.

sectigo_client_cert_validity

Mandatory

The certificate validity period in days (numeric). The values available are dependent on the selected sectigo_ssl_cert_type.

sectigo_client_cert_email

Mandatory

The valid user’s email. Must not be empty. Must be less than 256 characters.

sectigo_client_cert_first_name

Mandatory

The user’s first name

sectigo_client_cert_middle_name

Conditional

The user’s middle name

sectigo_client_cert_last_name

Mandatory

The user’s last name. The combined length of the first, middle, and last name fields cannot exceed 64 characters.

sectigo_client_cert_custom_fields

Optional

Custom fields to be applied to the requested certificate. The expected format for custom fields is [{"name":"custom_field_1","value":"value_1"},{"name":"custom_field_2","value":"value_2 "}]. If you are providing this input in a JSON string, ensure that the internal double quotes are escaped properly using \.

In addition to the parameters listed in the preceding table, you are required to pass the CSR parameters.

CollectCertificate

The following table lists parameters that are used for collecting a certificate. The collection operation may fail if the certificate is still being processed. In such cases, the operation attempts to collect the certificate several times before returning a failure. The parameters allow you to configure the frequency and maximum time for additional attempts during certificate collection.

Parameter Type Description

SSL certificates

sectigo_ssl_cert_format_type

Mandatory (with default)

The format type for the SSL certificate. The supported values are:

  • x509: X509, Base64 ended (default)

  • x509CO: X509 certificate only, Base64 encoded

  • x509IO: X509 intermediates and root only, Base64 encoded

  • base64: PKCS#7 Base64 encoded

  • bin: PKCS#7 Bin encoded

  • x509IOR: X509 intermediates and root only reverse, Base64 encoded

sectigo_loop_period

Mandatory (with default)

The interval (in seconds) between repeated attempts to collect a certificate (numeric). The default value is 30.

sectigo_max_timeout

Mandatory (with default)

The maximum time (in seconds) during which repeated attempts to collect a certificate will be made (numeric). The default value is 600.

sectigo_ssl_cert_ssl_id

Mandatory

The SSL ID of the certificate to be collected

Client certificates

sectigo_loop_period

Mandatory (with default)

The interval (in seconds) between repeated attempts to collect a certificate (numeric). The default value is 30.

sectigo_max_timeout

Mandatory (with default)

The maximum time (in seconds) during which repeated attempts to collect a certificate will be made (numeric). The default value is 600.

sectigo_client_cert_order_number

Mandatory

The Order Number of the certificate to be collected

In managed endpoints, the sectigo_ssl_cert_ssl_id and sectigo_client_cert_order_number fields do not have to be specified. A fresh enrollment creates a .ids file that includes the applicable certificate ID which then is read during the CollectCertificate operation. If you want to collect or replace a specific certificate ID, and the .ids field does not exist, you may specify the values for the sectigo_ssl_cert_ssl_id and sectigo_client_cert_order_number fields.

RenewCertificate

The following table lists parameters that are used for renewing a certificate.

Parameter Type Description

SSL certificates

sectigo_ssl_cert_ssl_id

Mandatory

The SSL ID of the certificate to be collected

Client certificates

sectigo_client_cert_order_number

Mandatory

The Order Number of the certificate to be collected

ReplaceCertificate

The following table lists parameters that are used for replacing a certificate.

Parameter Type Description

SSL certificates

sectigo_csr

Mandatory

The SSL ID of the certificate to be collected

sectigo_replace_reason

Mandatory

Reason for replacing the certificate

sectigo_ssl_cert_common_name

Mandatory

Single value for a domain included in the certificate Common Name (CN) field

sectigo_ssl_cert_subject_alt_names

Optional

A comma-separated list of subject alternative names (SAN)

sectigo_ssl_cert_ssl_id

Mandatory

The SSL ID of the certificate to be replaced

Client certificates

sectigo_csr

Mandatory

The SSL ID of the certificate to be collected

sectigo_replace_reason

Mandatory

Reason for replacing the certificate

sectigo_client_cert_revoke_on_replace

Mandatory (with default)

If true, previous certificates will be revoked when replaced. The default value is false.

sectigo_client_cert_order_number

Mandatory

The Order Number of the certificate to be replaced

RevokeCertificate

The following table lists parameters that are used for revoking a certificate.

Parameter Type Description

SSL certificates

sectigo_revoke_reason

Mandatory

The reason why a certificate is to be revoked

sectigo_ssl_cert_ssl_id

Mandatory

The SSL ID of the certificate to be collected

Client certificates

sectigo_revoke_reason

Mandatory

The reason why a certificate is to be revoked

sectigo_client_cert_order_number

Mandatory

The Order Number of the certificate to be collected

Managed API endpoint parameters

RequestManagedCertificate

The following table lists parameters that are used for requesting a managed certificate.

Parameter Type Description

Request managed SSL certificate parameters

sectigo_ssl_cert_file_path

Mandatory

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs.

sectigo_ssl_cert_file_name

Mandatory

The name of the certificate file. The same name is used for the CSR, private key, and enrollment IDs.

sectigo_force

Mandatory (with default)

Issues a new certificate even if there is already a certificate on the target server. The default value is false. If set to true, the existing certificate is backed up and any related information (key, CSR, ID) is deleted. This option is required if the certificate information (such as domain) has changed and a new certificate is required.

sectigo_expiry_window

Mandatory (with default)

The period of days prior to expiration that a new certificate enrollment process will be initiated (numeric). The default expiry window is 7 days.

sectigo_auto_renew

Mandatory (with default)

If set to true, the auto-renewal option is enabled. The default value is true.

Request managed client certificate parameters

sectigo_client_cert_file_path

Mandatory

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs.

sectigo_client_cert_file_name

Mandatory

The name of the certificate file. The same name is used for the CSR, private key, and enrollment IDs.

sectigo_force

Mandatory (with default)

Used to issue a new certificate even if there is already a certificate on the target server. The default value is false. If set to true, the existing certificate is backed up and any related information (key, CSR, ID) is deleted. This option is required if the certificate information (such as domain) has changed and a new certificate is required.

sectigo_expiry_window

Mandatory (with default)

The period of days prior to expiration that a new certificate enrollment process will be initiated (numeric). The default expiry window is 7 days.

sectigo_auto_renew

Mandatory (with default)

If true, the auto-renewal option is enabled. The default value is true.

In addition to the parameters listed in the preceding table, you are required to pass the following parameters:

The following diagram illustrates the RequestManagedCertificate flow.

Java Sectigo RequestManagedCertificate flow

ReplaceManagedCertificate

The following table lists parameters that are used for replacing a managed certificate.

Parameter Type Description

sectigo_ssl_cert_file_path

Mandatory

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs.

sectigo_ssl_cert_file_name

Mandatory

The name of the certificate file. The same name is used for the CSR, private key, and enrollment IDs.

sectigo_generate_key_if_missing

Mandatory (with default)

If true, generates the private key if it is missing. The default value is false.

Replace managed client certificate parameters

sectigo_client_cert_file_path

Mandatory

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs.

sectigo_client_cert_file_name

Mandatory

The name of the certificate file. The same name is used for the CSR, private key, and enrollment IDs.

sectigo_generate_key_if_missing

Mandatory (with default)

If set to true, generates the private key if it is missing. The default value is false.

In addition to the parameters listed in the preceding table, you are required to pass the following parameters:

The following diagram illustrates the ReplaceManagedCertificate flow.

Java Sectigo ReplaceManagedCertificate flow

Using the SDK

To use the SDK, you need to configure your directory structure and then you can start interacting with the library.

How to configure the work directory structure

The packaged SDK is shipped as a JAR file that you include in your project, and then import the required classes, such as com.sectigo.jcert.JCert.

import com.sectigo.jcert.JCert;

How to interact with the library

The sample.java file provided with the SDK package includes examples of how to use the sectigo-jcert library in your code and how to call managed and unmanaged API endpoints. For information on parameters to pass to different API endpoints, see The SDK parameters.

Additional information

Handling files

Using unmanaged API endpoints does not result in file generation or reference. These endpoints only use parameters that you provide for interacting with SCM and return a JSON response to you.

Using managed API endpoints results in generation of certificate-related files and their storage in the sectigo_ssl_cert_file_path (for SSL certificates) and sectigo_client_cert_file_path (for client certificates) directories.

Auto-renewal of certificates

Certificate auto-renewal is implemented for the RequestManagedCertificate endpoint. If an existing certificate is expired or is about to expire (within the specified sectigo_expiry_window), the library tries to renew the certificate.

The existing certificate-related files are not deleted and only renamed with a timestamp.

Using existing CSRs

Although the library supports the generation of private keys and CSRs, you can supply your own custom CSR by passing the respective value in the parameters map using the sectigo_csr parameter (see CSR parameters). If you pass a CSR value explicitly using the sectigo_csr parameter, the library assumes that you have the private key that matches the given CSR.

Backup files

Files that are backed up have the following format.

`<filename>_<cert_id>_backup_<timestampInMilliseconds>.<extension>`

If there is no IDS file present when the backup is performed, the cert_id is set to 0.