CERIAL DOCS

CERIAL documentation

Introduction

CERIAL manages the lifecycle of certificates through the EST (Enrollment over Secure Transport) protocol. It provides automation for requesting and renewing X.509 digital certificates using EST.

In this document you will find the execution of CERIAL from a CLI and a description of the parameters for its configuration file and execution.

Running CERIAL

To execute the binary, you can use the following commands:

cerial.exe (--help | -h)
cerial.exe (--version | -v)
cerial.exe (--show) [--settings=<path_to_settings>]
cerial.exe [--settings=<path_to_settings_file>]
          [--logging=<path_to_logging_folder>]
          [--credentials=<basic_authentication>]

The execution commands surrounded with brackets [] indicates the optional flags. This means that without specifying them, the command will execute and will take default values.

The execution commands surrounded with parentheses () are mandatory to specify and without doing it, the command will not run properly. Pipe | means logical “or”, symbolizing that you may choose either of the command syntax.

  • -h or --help - Displays the manual with common available options provided by CERIAL. For more extensive explanation, use this online documentation.
  • -v or --version - Shows the version of CERIAL.
  • --show - Shows the configuration settings, which have been applied by the provided configuration. Important This setting can only be combined with the --settings switch, which defines the configuration file location. It is meant to test your settings file and show you how the settings are applied. This is especially useful, if you combine command line parameters with .ini file settings and make sure the correct settings have been used by CERIAL.
  • --settings - Provide the path to the settings.ini file, which contains the CERIAL configuration settings.
  • --logging - It is suggested to provide a separate log file path, otherwise CERIAL tries to write a log file in the folder, where the executable file is located. If the user, which executes CERIAL does not have write permissions in that folder, the log file could not be generated. For audit purposes, define a log file path, which is writable for the user, which executes CERIAL.

‍

Configuration

  • CERIAL's configuration is mainly managed through the settings.ini file, consisting of various sections with configurable options. Some configuration parameters can be defined in the command line, especially if they are different between executions. You can define the path to the configuration file with the command line parameter --settings=/path/to/settings.ini where the CERIAL execution user must have read permissions.
  • ; is used inside the settings.ini file to comment a line.
  • Configuration is case-sensitive, all the configuration options should be written in lower case.
  • The values for yes/no settings can be also shortened by y/n

‍

Section [general]

This section contains general configuration settings, which control the behavior of CERIAL.

opmode
Purpose:         Specifies the operations mode of the system, defining how it behaves.
Allowed Values:  auto | init | renew
Default Value:   auto
Command Line:    --opmode | -m

Description

CERIAL allows users to automatically manage certificates on their endpoints. This parameter controls the operational behavior of CERIAL and defines, which operations are performed.

  • auto
    CERIAL uses certificate search filters (config settings filter_* in section [csr]) to identify certificates it shall manage. CERIAL searches in the certificate store for certificates matching all filter criteria (logical condition is AND) and decides based on renewperiod, if a renew shall be performed.
  • init
    If CERIAL is started with this operations mode, it immediately triggers the issuance of a new certificate with the configured CSR settings (see [csr] section). It ignores the potential existence of similar certificates in the certificate store and enforces the enrollment of a new certificate. This option can be used when running CERIAL for the first time, by providing this operations mode from the command line, together with initial enrollment credentials (see parameter credentials in section [enrollserver]).
  • renew
    This operations mode forces CERIAL to search for a matching certificate in the certificate store and start the renewal of the matched certificate immediately. With this operations mode, CERIAL ignores the renewperiod configuration setting and forces the renewal of the found certificate.

‍

Section [general]

This section contains general configuration settings, which control the behavior of CERIAL.

opmode

Purpose:         Specifies the operations mode of the system
Allowed Values:  auto | init | renew
Default Value:   auto
Command Linie:   --opmode | -m

Description

CERIAL allows users to automatically manage certificates on their endpoints. This parameter controls the operational behavior of CERIAL and defines, which operations are performed.

  • auto - CERIAL uses certificate search filters (config settings filter_* in section [csr]) to identify certificates it shall manage. CERIAL searches in the certificate store for certificates matching all filter criteria (logical condition is AND) and decides based on renewperiod, if a renew shall be performed.
  • init - If CERIAL is started with this operations mode, it immediately triggers the issuance of a new certificate with the configured CSR settings (see [csr] section). It ignores the potential existence of similar certificates in the certificate store and enforces the enrollment of a new certificate. This option can be used when running CERIAL for the first time, by providing this operations mode from the command line, together with initial enrollment credentials (see parameter credentials in section [enrollserver]).
  • renew - This operations mode forces CERIAL to search for a matching certificate in the certificate store and start the renewal of the matched certificate immediately. With this operations mode, CERIAL ignores the renewperiod configuration setting and forces the renewal of the found certificate.
autoenroll
Purpose:         Defines if CERIAL automatically enrolls a new certificate, if no sufficient was found.
Allowed Values:  yes | no
Default Value:   no
Command Linie:   --autoenroll | -e

Description

CERIAL is able.........................

autorenew

Purpose:         Defines if CERIAL automatically enrolls a new certificate, if no sufficient was found.
Allowed Values:  yes | no
Default Value:   no
Command Linie:   --autoenroll | -e

‍

‍