Sectigo Client SDK for Golang integration

Overview

The Sectigo Client SDK is a set of tools that allow you to communicate with APIs from the 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 Golang 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, RevokeCertificate, and CollectProfiles

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

    • RequestManagedCertificate and ReplaceManagedCertificate

Sectigo Golang integration

Prerequisites

The Golang library has the following prerequisite:

  • Golang version 1.13

The library is supported and has been tested on the following operating systems:

  • Ubuntu Server 16.04 LTS

  • Ubuntu Server 18.04 LTS

  • Ubuntu Server 19.10

  • Ubuntu Server 20.04

  • CentOS 8.1

  • Windows 10

The Sectigo Client SDK for Golang contains the following:

  • sectigo-gocert:

    • *.go: A set of .go files that form the Golang Client SDK

    • go.mod: The SDK’s module path and its dependency requirements

  • sample:

    • sample.go: Sample code that demonstrates end-to-end examples of EnrollCertificate, CollectCertificate, and RequestManagedCertificate for SSL and client certificates

    • go.mod: The sample’s module path and its dependency requirements

Golang 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 the capability to generate a private key and a CSR which would 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.

  • CollectProfiles(params, certCategory): Collects a list of the certificate profiles from 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 the certificate if applicable, and updates certificate-related files accordingly. Provides the capability 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 is based on the function called. 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, ReplaceManagedCertificate, or CollectProfiles)

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 scm_response.

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 API call

timestamp

Time of the last operation

sub_operations

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

profiles_response

Response containing the list of certificate profiles.

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 API 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

Time of the last operation

status

The status of the operation: SUCCESS or FAILURE

message

A message describing the result of the operation

Sample responses

Unmanaged API endpoints.

Golang Sectigo unmanaged API endpoints

Managed API endpoints.

Golang 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 in megabytes 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_auth_type

Conditional

Authentication type to use with SCM connections. Supported parameters are password and client_cert. Defaults to password. Required for client certificate login

sectigo_cm_user

Mandatory

User ID to access your URI

sectigo_cm_password

Conditional

Password to access your URI. Mandatory for SCM connections requiring username and password

sectigo_cm_client_cert

Conditional

Client certificate in PEM format used to authenticate the SCM connection. Required if sectigo_cm_auth_type is client_cert.

sectigo_cm_private_key

Conditional

Private key in PEM format associated with the client certificate for SCM connection. Required if sectigo_cm_auth_type is client_cert.

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 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, generate the default RSA 2048-bit private key to be used for the CSR. Required if the 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 and sectigo_csr are not defined.

sectigo_csr_state

Conditional

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

sectigo_csr_location

Conditional

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

sectigo_csr_organization

Conditional

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

sectigo_csr_organization_unit

Conditional

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

sectigo_csr_email_address

Conditional

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

sectigo_csr

Conditional

A certificate signing request in PEM format that users can optionally provide if they don’t want to generate a new one. 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 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

A certificate signing request in PEM format with updated parameters.

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

A certificate signing request in PEM format with updated parameters.

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

CollectProfiles

The following table lists parameters that are used for collecting certificate profiles for an organization.

Parameter Type Description

SSL certificates

sectigo_cm_org_id

Optional

Your organization ID (numeric)

Client certificates

sectigo_cm_org_id

Optional

Your organization ID (numeric)

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 the 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 the 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.

Golang Sectigo RequestManagedCertificate flow

ReplaceManagedCertificate

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

Parameter Type Description

Replace 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 the 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 the 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.

Golang 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 set of Go source code files and a go.mod file that are stored in the sectigo-gocert directory. One way to import the library into your project is by including the sectigo-gocert directory in your work directory, and by directly referencing the library using your own go.mod file.

Your work directory may have the following structure.

base_work_directory/
base_work_directory/custom_project/
base_work_directory/sectigo-gocert/

The custom_project would include your own source code and go.mod file which needs to import sectigo-gocert.

module sectigo-gocert-sample-app
go 1.13
replace module sectigo-gocert v1.0.0 => ../sectigo-gocert
require sectigo-gocert v1.0.0

Once the work directory is set up, you may import the library into your Go source code file by using an import statement.

package main

import (
    scert "sectigo-gocert"
)

The preceding code imports sectigo-gocert and associates it with it the scert alias that can be used to interact with the library’s endpoints.

How to interact with the library

The sample.go file provided with the SDK package includes examples of how to import the sectigo-gocert library into 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.

To use sample.go, switch your work directory to the sample directory provided with the SDK package, customize the parameters in the sample.go file to match your settings, and run the following command.

$ go run sample.go

The preceding command automatically fetches the dependencies that are required by the library and executes the code in the sample.go file.

Additional information

Handling files

Using unmanaged API endpoints does not result in files 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.