Sectigo Chef integration

Overview

The Sectigo Chef integration provides a solution for the enrollment, collection, renewal, replacement, and revocation of SSL/TLS and client (S/MIME) certificates issued by the Sectigo Certificate Manager (SCM).

The integration is distributed as a Chef cookbook. It provides the following features:

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

  • Certificate signing request (CSR)

  • Enrollment, collection, renewal, replacement, and revocation of certificates issued by SCM

The integration supports the generation of new SSL and client certificates and detection of existing certificates stored in a location accessible to the cookbook at runtime. The integration also checks the validity of existing certificates and allows the issuance of replacement certificates as required. There are various types of SSL and client certificates that can be requested by supplying the appropriate configuration options.

The types of SSL/TLS and client certificates available to you are based on your account setup.
Chef Sectigo integration

Prerequisites

The Chef integration has the following prerequisites:

  • Chef Workstation 0.17.5

  • Chef Server 13.2.0

  • Chef Client Node 15.8.23

  • Ruby version 2.7

  • SCM organization with the Web API access enabled

  • A list of SSL and client certificate types with associated terms for the organization

The integration is supported on Linux Workstation, Linux Server, and Linux Node, and has been tested on the following operating systems:

  • Linux CentOS 7.3 WorkStation, Server, and Nodes

  • Ubuntu 16.04 and 18.04 WorkStation, Server, and Nodes

Chef integration package

The Sectigo Chef integration package contains the following:

  • attributes:

    • default.rb: The configuration data for the SSL or client certificate

  • libraries:

    • constants.rb: The constants file for the SCM API library

    • sectigo_rbcert.rb: The Ruby library for connecting with the SCM API by chef recipes

    • sectigo_certificate_helper.rb: The common function used by chef recipes

  • recipes:

    • collect_certificate.rb: The recipe to collect the certificate

    • copy_certificate.rb: The recipe that copies certificate-related files from the cookbook file to node

    • issue_certificate.rb: The recipe that issues the certificate

    • replace_certificate.rb: The recipe that replaces the certificate and collects the updated certificate

    • revoke_certificate.rb: The recipe that revokes the certificate

  • samples: Contains the following sample parameter JSON files:

    • sectigo_chef_node.sh: The shell executable file. Used only to execute cookbook on the chef node.

    • sectigo_chef_workstation.sh: The chef executable file. Used only to execute cookbook on the chef workstation.

    • *.json: Sample JSON parameter files that may be used for different recipes.

Sectigo Chef integration package

The integration structure

The integration hides the complexity of the SCM REST API by acting as an adapter between Chef and the Sectigo API. It enables you to request, replace, renew, and revoke certificates on your WorkStation and Client nodes.

Components

The integration is based on the following components:

  • Ruby client library for the Sectigo API handles the communication with the Sectigo REST API. This library is a component of the Chef cookbook. It is not designed or delivered as a general-purpose library.

  • Chef cookbook mediates the interaction between you, the Chef master and client nodes, and the Sectigo REST API. The cookbook mainly consists of a standard Chef execution routine with minimum dependencies. It supports the enrollment, collection, replacement, renewal, and revocation of SSL and client certificates.

Chef cookbook is the only software component that can interact with the library.

Sectigo Chef recipes

The following recipes allow you to interact with SCM and perform different operations. In order to trigger any of these recipes, you must add the recipe that you want to run in the run_list attribute in the used JSON file (the package includes sample JSON files) that includes all the parameters:

  • Issue certificate:

    • Enrolls and collects a certificate from SCM

    • Stores and maintains the .key, .csr, .crt, and .ids files

    • Checks an existing certificate’s validity and auto-renews it if required It also updates certificate-related files accordingly

    • Allows you to generate a private key and a CSR.

      Use the issue_certificate entry in your run_list in the samples/ssl_params.json or samples/client_params.json file.

      "run_list": [
          "recipe[sectigo_chef_cookbook::issue_certificate]"
      ]
  • Replace certificate:

    • Replaces an existing certificate on SCM by using the certificate ID from the .ids file (which must already exist). The replaced certificate is collected and the certificate-related files are updated accordingly.

      Use the replace_certificate entry in your run_list in the samples/ssl_params.json or samples/client_params.json file.

      "run_list": [
          "recipe[sectigo_chef_cookbook::replace_certificate]"
      ]
  • Revoke certificate:

    • Revokes a certificate on SCM by using the certificate ID from the IDs file (which must already exist).

      Use the revoke_certificate entry in your run_list in the samples/ssl_params.json or samples/client_params.json file.

      "run_list": [
          "recipe[sectigo_chef_cookbook::revoke_certificate]"
      ]
  • Collect certificate:

    • Collects a certificate from SCM using the input for sectigo_ssl_cert_ssl_id or sectigo_client_cert_order_number provided to you.

      Use the collect_certificate entry in your run_list in the samples/ssl_collect.json or samples/client_collect.json file.

      "run_list": [
          "recipe[sectigo_chef_cookbook::collect_certificate]"
      ]
  • Copy certificate:

    • Copies certificate-related files from the Chef server onto a Chef node. When using this recipe, ensure that your existing certificate-related files are under the files subdirectory of your sectigo_chef_cookbook directory. The certificate-related files are then copied to the destination that you specify in your JSON file. If the files subdirectory does not exist, you need to create it and manually add the certificate-related files to it.

      In the copy_certificate recipe, ensure that you specify the file name that you want to copy. In other words, ensure that your sectigo_ssl_cert_file_name (or sectigo_client_cert_file_name) parameters for copy_certificate match the parameters that you used in the previous recipe (issue_certificate, replace_certificate, or collect_certificate).

      Use the copy_certificate entry in your run_list in the samples/ssl_copy.json or samples/client_copy.json file.

      "run_list": [
          "recipe[sectigo_chef_cookbook::copy_certificate]"
      ]

The integration parameters

The integration 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.

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 Sectigo URI

sectigo_cm_base_url

Mandatory

The base URL of the Sectigo CA

CSR parameters

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

Parameter Type Description

sectigo_csr_domain

Conditional

A single value for a domain included in the certificate Common Name (CN) field.

Required if sectigo_csr is not defined.

sectigo_csr_country

Conditional

The country name included in the certificate Country (C) field.

Required if 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 is not defined.

sectigo_csr_location

Conditional

The location name included in the certificate Location (L) field.

Required if sectigo_csr is not defined.

sectigo_csr_organization

Conditional

The organization name included in the certificate Organization (O) field.

Required if 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 is not defined.

sectigo_csr_email_address

Conditional

The email address included in the certificate emailAddress field.

Required if sectigo_csr is not defined.

sectigo_csr

Conditional

The full path to 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

The size of the TLS/SSL key to generate. The possible values are:

  • 2048: for 2048-bit (default)

  • 3072: for 3072-bit

  • 4096: for 4096-bit

Certificate issuance parameters

The following table lists parameters that are used for certificate issuance.

Parameter Type Description

SSL certificates

sectigo_cm_org_id

Mandatory

Your organization ID (numeric)

sectigo_ssl_cert_file_path

Mandatory (with default)

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs. The default file path is the one where the command is executed. For the chef- solo command , the root folder / is the execution folder.

sectigo_ssl_cert_file_name

Mandatory (with default)

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

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 the following: [{"name":"custom_field_1","value":"value_1"},{"name":"custom_field_2","value":"value_2"}]. If you are providing this input in a JSON string, make sure that the internal double quotes are escaped properly using \.

sectigo_ssl_cert_format_type

Optional

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

  • x509: X509, Base64 encoded

  • x509CO: X509 certificate only, Base64 encoded (default)

  • x509IO: X509 Intermediates/Root only, Base64 encoded

  • base64: PKCS#7 Base64 encoded

  • bin: PKCS#7 Bin encoded

  • x509IOR: X509 Intermediates/Root only Reverse, Base64 encoded

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_type

Mandatory

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

Client certificates

sectigo_cm_org_id

Mandatory

Your organization ID (numeric)

sectigo_client_cert_file_path

Mandatory (with default)

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs. The default file path is from where the command is executed. For the chef- solo command, the root folder / is the execution folder.

sectigo_client_cert_file_name

Mandatory (with default)

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

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

A valid user email that is 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 the following: [{"name":"custom_field_1","value":"value_1"},{"name":"custom_field_2","value":"value_2"}]. If you are providing this input in a JSON string, make sure that the internal double quotes are escaped properly using \.

sectigo_client_cert_subject_alt_names

Optional

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

sectigo_client_cert_revoke_on_replace

Optional

If True, previous certificates will be revoked when replaced. The default value is False.

Certificate auto-renewal

sectigo_expiry_window

Optional

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

sectigo_auto_renew

Optional

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

Collect certificate

sectigo_loop_period

Optional

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

sectigo_max_timeout

Optional

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

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

Certificate collection parameters

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

Optional

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

sectigo_max_timeout

Optional

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

Conditional

The SSL ID of the certificate to be collected. Mandatory if the selected recipe is collect_certificate.

sectigo_ssl_cert_file_path

Optional

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs. The default file path is the one where the command is executed. For the chef- solo command, the root folder / is the execution folder.

sectigo_ssl_cert_file_name

Optional

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

Client certificates

sectigo_loop_period

Optional

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

sectigo_max_timeout

Optional

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_file_name

Optional

The order number of the certificate to be collected

sectigo_client_cert_file_path

Optional

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs. The default file path is the one where the command is executed. For the chef- solo command, the root folder / is the execution folder.

sectigo_client_cert_order_number

Conditional

The order number of the certificate to be collected. Mandatory if the selected recipe is collect_certificate.

Certificate replacement parameters

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

Parameter Type Description

SSL certificates

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_generate_key_if_missing

Mandatory (with default)

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

Client certificates

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

sectigo_generate_key_if_missing

Mandatory (with default)

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

In addition to the parameters listed in the preceding table, you are required to pass CSR parameters that are listed in CSR parameters, as per your replacement requirement. For more information, see Replacing certificates.

Certificate revocation parameters

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

Parameter Type Description

SSL certificates

sectigo_revoke_reason

Mandatory

The reason why a certificate is to be revoked

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

Client certificates

sectigo_revoke_reason

Mandatory

The reason why a certificate is to be revoked

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

Miscellaneous parameters

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

Parameter Type Description

sectigo_force

Optional

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_cert_type

Mandatory

Indicates the type of the certificate. Should be set to ssl for SSL certificates and to client for client certificates.

Using the integration

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

How to configure the work directory structure

You start configuration by unzipping the files and directories that are included in the packaged integration into the cookbooks folder of Chef, with the default typically located under /var/chef.

Every time you execute the knife command, you need to configure the file in the default location (current_location/.chef/config.rb). Alternatively, you can pass the configuration file while executing the knife command using the -config option. For example, -config config.rb.

How to set up environment variables

There are three environment variables that must be specified as part of this package. These variables are located in the root user on the workstation and in the logged-in user on the Chef node. If you are interacting with the Bash directly on the Chef workstation or on your Chef node, you can set the following in your ~/.bashrc file.

export SECTIGO_CM_USER='<your_Sectigo_username>'
export SECTIGO_CM_PASSWORD='<your_Sectigo_password>'
export SECTIGO_CM_URI='<your_Sectigo_URI>'

The Linux command to set these environment variables after adding them in ~/.bashrc is $ source ~/.bashrc.

If you are interacting with your Chef node remotely—​for example, through knife ssh, you need to add the following lines to your /etc/environment file.

SECTIGO_CM_USER='<your_Sectigo_username>'
SECTIGO_CM_PASSWORD='<your_Sectigo_password>'
SECTIGO_CM_URI='<your_Sectigo_URI>'

How to execute the Chef cookbooks

You can use the integration to issue, collect, replace, and revoke certificates.

Issuing certificates

To issue a certificate, you use the issue_certificate recipe described in Sectigo Chef recipes. Ensure you set the sectigo_cert_type parameter to ssl or client, depending on the certificate type with which you are working.

Using the Chef workstation to issue certificates

You can issue certificates via the Chef workstation as follows:

  1. Get the latest certificate by executing the existing recipes using the following command.

     chef-solo -j samples/ssl_params.json --log_level info

    Where samples/ssl_params.json is the parameter in the JSON file given in the package.

    {
        "run_list": [
            "recipe[sectigo_chef_cookbook::issue_certificate]"
        ],
        # customer specific
        "sectigo_cm_base_url":"https://<REPLACE_SECTIGO_CM_PORTAL>",
        "sectigo_cm_org_id":12345,
        "sectigo_cert_type":"ssl",
            .
            .
    }
  1. Once the certificate is issued and collected, upload the cookbook to the Chef server by executing the following command:

    knife cookbook upload sectigo_chef_cookbook -cookbook-path /var/chef
  1. Configure the parameters for your Chef node by executing the following command.

    knife node edit name_of_chef_node

    Once the cookbook is uploaded to the Chef server, you can obtain the certificate on a Chef node by executing the following command.

    knife ssh 'name: name_of_chef_node' 'sudo chef-client'

    Where name_of_chef_node is the name of your Chef node. The <name_of_chef_node>.json file that is associated with your Chef node should be similar to the following.

    {
        "run_list": [
            "recipe[sectigo_chef_cookbook::copy_certificate]"
        ],
        # parameters
        "normal": {
            "sectigo_cert_type":"ssl", "sectigo_ssl_cert_file_path":"/etc/ssl/",
            "sectigo_ssl_cert_file_name":"sectigo_ssl",
             .
        }
         .
         .
    }

    The same command may be used to trigger other recipes.

The following diagram illustrates the certificate issuance flow.

Sectigo Chef certificate issuance diagram
Executing the local cookbook on Chef nodes to issue certificates

You may issue different certificates on each individual Chef node by running the following command, where samples/ssl_params.json is the parameter in the JSON file given in the package.

sudo chef-client -j sample/ssl_params.json --log_level debug
Executing the remote cookbook on Chef nodes to issue certificates

In order to execute recipes remotely on Chef nodes, run the following commands:

  1. Modify your Chef node to specify the recipe to use along with its applicable parameters.

    knife node edit name_of_chef_node
  1. Trigger the recipe.

    knife ssh 'name:name_of_chef_node' 'sudo chef-client'

    Where name_of_chef_node is the name of your Chef node. The <name_of_chef_node>.json file that is associated with your Chef node should be similar to the following.

    {
        "run_list": [
            "recipe[sectigo_chef_cookbook::recipe_you_want_to_execute]"
        ],
        # parameters
        "normal": {
            "sectigo_cm_base_url":"https://<REPLACE_SECTIGO_CM_PORTAL>",
            "sectigo_cm_org_id":12345,
            "sectigo_cert_type":"ssl",
             .
        }
         .
         .
    }

Replacing certificates

A certificate can be replaced if one of the following conditions is met:

  • A CSR value is provided via the sectigo_csr parameter, and a value has been modified for any of the sectigo_csr, domain, or SANs parameters.

  • A value has been modified for any individual CSR, domain, or SANs parameters.

To replace a certificate, follow the Replace certificate recipe in Sectigo Chef recipes.

The following diagram illustrates the certificate replacement flow.

Sectigo Chef certificate replacement diagram

Revoking certificates

To revoke a certificate, follow the Revoke certificate recipe in Sectigo Chef recipes.

Collecting certificates

To collect a certificate, follow the Collect certificate recipe in Sectigo Chef recipes.

How to configure logging

The integration includes a logger that you can configure using parameters described in the following table. In the integration:

  • Logs are always stored in a log file whose path is configurable.

  • Logs can be sent to STDOUT.

  • Logs are rotated based on a maximum file size (for example, 10240000 bytes). The maximum file size and the maximum number of backed up log files are configurable.

Parameter Type Description

sectigo_logger_file_path

Optional

The path where the logs are stored. The default value is ./sectigo_chef_cookbook.log.

sectigo_logger_stdout_flag

Optional

A flag that determines if logs are sent to STDOUT. The default value is true.

sectigo_logger_max_file_size

Optional

The maximum file size for the rotated logs in bytes. The default value is 10240000.

sectigo_logger_max_num_backups

Optional

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

How to use existing CSRs

You can provide an existing CSR by enabling the sectigo_csr parameter in the param.json file and supplying the file path. The cookbook will use this CSR instead of creating new one. The certificate enrollment, renewal, replacement, and collection uses the content from the provided sectigo_csr parameter.

How to automate the execution of the cookbook on the Chef workstation

The sectigo-chef-workstation.sh script included in the integration’s package can be used as a cronjob (see Crontab.guru). It is executed at the defined time interval and runs all the commands defined in the script. The following example shows how to use crontab to run a cronjob, with the configuration on the workstation user root user.

PATH=/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin:/usr/local/go/bin
* */2 * * * . ~/.bashrc; /home/centos/samples/sectigo-chef-workstation.sh >>
/home/centos/ /home/centos/samples/daily-backup.log 2>&1

The issue_certificate, replace_certificate, collect_certificate, or revoke_certificate recipe is used in the run_list to run on the workstation. The copy_certificate recipe in the run_list is only used for the Chef node. The preceding example executes the script for SSL every 2 hours.

Each location must be an absolute path.

How to automate the execution of the cookbook on Chef nodes

The sectigo-chef-node.sh script included in the integration’s package can be used as a cronjob (see Crontab.guru). It is executed at the defined time interval and runs all the commands defined in the script. The following example shows how to use crontab to run a cronjob, with the configuration on the client node.

PATH=/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin:/usr/local/go/bin
* */2 * * * . ~/.bashrc; /home/centos/samples/sectigo-chef-node.sh >>
/home/centos/ /home/centos/samples/daily-backup.log 2>&1

The use issue_certificate, replace_certificate, collect_certificate, or revoke_certificate recipe is used in the run_list to run to the node. The preceding example executes the sectigo-chef-node.sh script for SSL every 2 hours.