CERIAL DOCS

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.

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 [certinfo]

This section covers certificate validation settings that ensure the authenticity and trustworthiness of certificates used within the system. Proper validation of certificates is a critical aspect of security, preventing the use of expired, revoked, or untrusted certificates that could compromise secure communications.

The settings in this section control whether certificates and their associated chains of trust are validated, as well as whether real-time certificate status verification (e.g., via OCSP) is performed. Enabling these options strengthens security by ensuring that only valid and trusted certificates are accepted, reducing the risk of unauthorized access or man-in-the-middle attacks.

The following parameters define the certificate validation behavior.

validate_tls_certificate_chain

Purpose:         Determines whether the certificate chain should be validated.
Allowed Values:  yes | no
Default Value:   yes
Command Line:    validate_tls_certificate_chain

‍Description

Controls whether the system should verify the full chain of trust for a certificate. When enabled, it checks that each certificate in the chain (from the end-entity certificate to the root CA) is valid and properly signed. If any certificate in the chain is missing, expired, or untrusted, the validation fails, ensuring that only trusted certificates are used for secure communications.

• yes
  ‍Enables full validation of the certificate chain, ensuring that each certificate in the chain is valid and trusted.

• no
  ‍Disables chain validation, which may allow the use of untrusted or self-signed certificates.

validate_tls_certificate

Purpose:         Controls the validation of the TLS certificate against validation services (OCSP).
Allowed Values:  yes | no
Default Value:   yes
Command Line:    validate_tls_certificate

‍Description

Specifies whether the system checks the real-time status of the EST server TLS certificate. This validation is typically performed using Online Certificate Status Protocol (OCSP) or Certificate Revocation Lists (CRLs) to determine if a certificate has been revoked. Enabling this setting enhances security by preventing the use of revoked certificates.

• yes
  ‍Enables real-time certificate status checking using OCSP or on Windows the integrated Windows certificate store API.
• no
  ‍Skips certificate status validation, which may allow the use of revoked certificates.

‍

Section [enrollserver]

The enrollserver section defines the parameters required to connect to a certificate enrollment server. The server must support HTTPS, and the specified endpoints must be accessible and resolvable. This section ensures that certificate enrollment and renewal operations are performed securely and efficiently.

General rules:

• HTTPS is the only supported scheme. Communication must be encrypted to protect certificate requests and responses.
• <ip_address> must be an IPv4 address.
• <fqdn> stands for "Fully Qualified Domain Name" and must be resolvable by a DNS server to ensure proper communication with the enrollment server. Example : www.example.com
• <endpoint_path> defines the specific API path for enrollment or renewal requests. It can be the "root" path / or a custom path. Example: /est_server/endpoint
• The default value for <port> is 443.

enroll_endpoint

Purpose:         Specifies the endpoint for initial certificate enrollment.
Allowed Values:  https://<fqdn>:<port><endpoint_path> | https://<fqdn><endpoint_path> | https://<ip_address>:<port><endpoint_path> | https://<ip_address><endpoint_path>
Command Line:    enroll_endpoint

‍Description

The enroll_endpoint specifies the URL used to request the initial certificate enrollment from the certificate authority (CA). This endpoint must be accessible over HTTPS, ensuring secure communication during certificate provisioning. The URL can be defined using either a Fully Qualified Domain Name (FQDN) or an IP address, followed by an optional port number and endpoint path. The endpoint path is typically determined by the CA or the enrollment service provider. Proper DNS resolution is necessary when using an FQDN to prevent connectivity issues.

renew_endpoint

Purpose:         Specifies the endpoint for certificate renewal.
Allowed Values:  https://<fqdn>:<port><endpoint_path> | https://<fqdn><endpoint_path> | https://<ip_address>:<port><endpoint_path> | https://<ip_address><endpoint_path>
Command Line:    renew_endpoint

‍Description

The renew_endpoint defines the URL for renewing existing certificates before they expire. This endpoint functions similarly to the enroll_endpoint, except it is used specifically for renewal operations rather than initial enrollment. The renewal process helps maintain uninterrupted security by ensuring that certificates are updated before they reach expiration. It follows the same format and requirements as the enroll_endpoint, supporting both FQDN and IP-based configurations over HTTPS. Organizations typically automate renewal processes using this endpoint to avoid service disruptions caused by expired certificates.

credentials

Purpose:         Specifies the credentials for initial or renew enrollment.
Allowed Values:  <username>:<password>
Command Line:    credentials

‍Description

The credentials option defines the authentication credentials required for certificate enrollment and renewal requests. It consists of a username:password pair that is used to verify access to the certificate enrollment service. Secure storage and transmission of these credentials are critical to prevent unauthorized access or potential security risks.

‍

Section [csr]

This section defines the parameters used to generate a certificate signing request (CSR). It contains information about the entity requesting the certificate, including its common name (CN), organization (O), country (C), and other identifiers. The CSR configuration ensures that key pairs are generated using the appropriate algorithms, key sizes, and subject details. Additionally, the filtering options allow for better management of certificate requests by specifying criteria based on subject and issuer attributes. Proper CSR generation and filtering contribute to enhanced security and streamlined certificate lifecycle management.

Below are the available configuration options for CSR generation and certificate filtering.

keyalgorithm

Purpose:         Specifies the key algorithm for the key pair, created to generate a new CSR.
Allowed Values:  rsa | p256 | p384 | p521
Default Value:   rsa
Command Line:    keyalgorithm

‍Description

Defines the cryptographic algorithm used to generate the key pair for the CSR. Supported algorithms include RSA and various elliptic curve cryptography (ECC) options. ECC key types (p256, p384, p521) provide enhanced security with smaller key sizes.

• In case of using ECC key types, ignore the "keysize" parameter, because just RSA keys require explicit key size configuration, for ECC keys the key size is implicit in the chosen key type.

keysize

Purpose:        Specifies the key size for the CSR. Only used if in “keyalgorithm” the value “rsa” is configured.
Allowed Values:  “A number which is multiple of 8 and between 768 and 4096“
Default Value:   2048
Command Line:    keysize

Description

Specifies the size of the RSA key pair when generating a CSR. The value must be a multiple of 8 and within the range of 768 to 4096 bits. A larger key size enhances security but may impact performance. If an ECC key algorithm is selected, this parameter is ignored.

csr_e

Purpose:         Specifies the email address for the CSR.
Allowed Values:  <string>
Command Line:    csr_e

‍Description

Defines the email address associated with the certificate request. This information may be required by certain certificate authorities or used for administrative purposes.

csr_l

Purpose:         Specifies the locality for the CSR.
Allowed Values:  <string>
Command Line:    csr_l

‍Description

Represents the locality (city or region) of the entity requesting the certificate. This information is embedded in the CSR and helps identify the certificate holder.

csr_s

Purpose:         Specifies the state for the CSR.
Allowed Values:  <string>
Command Line:    csr_s

‍Description

Specifies the state or province of the entity requesting the certificate. Like locality, this field is used for identification within the CSR.

csr_cn

Purpose:         Specifies the common name (CN) for the CSR.
Allowed Values:  <string>
Default Value:   <hostname>
Command Line:    csr_cn

Description

Defines the Common Name (CN) for the CSR, which typically represents the domain name or hostname of the certificate requester. This is one of the most critical fields in the CSR, as it directly corresponds to the entity for which the certificate is issued. Example: bxc-common.name.

csr_ou

Purpose:         Specifies the organizational unit (OU) for the CSR.
Allowed Values:  <string>
Command Line:    csr_ou

‍Description

Represents the Organizational Unit (OU) requesting the certificate. This field is optional but may be used to distinguish different departments or teams within an organization. Example: OT PCs.

csr_org

Purpose:         Specifies the organization (O) for the CSR.
Allowed Values:  <string>
Command Line:    csr_org

‍Description

Specifies the full Organization Name (O) of the certificate requester. This field is included in the CSR to identify the legal entity associated with the certificate. Example: Engineering Unit.

csr_country

Purpose:         Specifies the country (C) for the CSR.
Allowed Values:  “Two-Letter String”
Command Line:    csr_country

‍Description

Defines the Country (C) associated with the CSR using a two-letter country code based on ISO 3166 standards. Example: DE for Germany.

csr_san

Purpose:         Specifies the subject alternative names (SANs) for the CSR.
Allowed Values:  dns:<fqdn> | ip:<ip_address>
Command Line:    csr_san

‍Description

Specifies the Subject Alternative Names (SANs) for the certificate request. SANs allow multiple domain names or IP addresses to be included in a single certificate, improving flexibility.

• Multiple values can be provided using the | separator. Example: dns:example.com|ip:1.2.3.4.

filter_subject

Purpose:         Specifies subject criteria for filtering certificates.
Allowed Values:  <string>
Command Line:    filter_subject

‍Description

Filters certificates based on subject-related attributes, allowing administrators to select certificates that match specific criteria within the subject field.

filter_rootski

Purpose:         Specifies the subject key identifier of the root CA certificate for filtering.
Allowed Values:  <string>
Command Line:    filter_rootski

‍Description

Filters certificates based on the Subject Key Identifier (SKI) of the root CA. This ensures that only certificates issued by a specific root CA are considered.

filter_subject_country

Purpose:         Specifies filter logic for certificates based on the country (C) in the subject field.
Allowed Values:  <string>
Command Line:    filter_subject_country

‍Description

Filters certificates by the Country Code (C) in the subject field, helping to organize certificates by geographic origin.

filter_issuer_country

Purpose:         Specifies filter logic for certificates based on the country (C) of the issuer.
Allowed Values:  <string>
Command Line:    filter_issuer_country

‍Description

Filters certificates based on the Country Code (C) of the issuing certificate authority. This is useful for managing certificates issued by CAs from different regions.

filter_subject_cn

Purpose:         Specifies filter logic for certificates based on the common name (CN) in the subject field.
Allowed Values:  <string>
Command Line:    filter_subject_cn

‍Description

Filters certificates based on the Common Name (CN) in the subject field, enabling selection of certificates assigned to specific domains or entities.

filter_issuer_cn

Purpose:         Specifies filter logic for certificates based on the common name (CN) of the issuer.
Allowed Values:  <string>
Command Line:    filter_issuer_cn

‍Description

Filters certificates based on the Common Name (CN) of the issuing CA, allowing for selection of certificates issued by a specific authority.

filter_subject_dn

Purpose:         Specifies filter logic for certificates based on the distinguished name (DN) in the subject field.
Allowed Values:  <string>
Command Line:    filter_subject_dn

‍Description

Filters certificates using the full Distinguished Name (DN) of the subject, ensuring precise matching based on multiple certificate attributes.

filter_issuer_dn

Purpose:         Specifies filter logic for certificates based on the distinguished name (DN) of the issuer.
Allowed Values:  <string>
Command Line:    filter_issuer_dn

‍Description

Filters certificates based on the Distinguished Name (DN) of the issuing CA, allowing administrators to work with certificates from particular issuers.

filter_subject_e

Purpose:         Specifies filter logic for certificates based on the Email (E) in the subject field.
Allowed Values:  <string>
Command Line:    filter_subject_e

‍Description

Filters certificates based on the Email Address (E) in the subject field, useful for selecting certificates issued to individuals.

filter_issuer_e

Purpose:         Specifies filter logic for certificates based on the Email (E) of the issuer.
Allowed Values:  <string>
Command Line:    filter_issuer_e

‍Description

Filters certificates by the Email Address (E) of the issuer, helping to identify certificates issued by specific authorities.

filter_subject_l

Purpose:         Specifies filter logic for certificates based on the locality (L) in the subject field.
Allowed Values:  <string>
Command Line:    filter_subject_l

‍Description

Filters certificates based on the Locality (L) in the subject field, grouping certificates by city or region.

filter_issuer_l

Purpose:         Specifies filter logic for certificates based on the locality (L) of the issuer.
Allowed Values:  <string>
Command Line:    filter_issuer_l

‍Description

Filters certificates by the Locality (L) of the issuing CA, aiding in management based on geographical criteria.

filter_subject_org

Purpose:         Specifies filter logic for certificates based on the organization (O) in the subject field.
Allowed Values:  <string>
Command Line:    filter_subject_org

‍Description

Filters certificates based on the Organization (O) in the subject field, allowing selection of certificates belonging to a specific company or entity.

filter_issuer_org

Purpose:         Specifies filter logic for certificates based on the organization (O) of the issuer.
Allowed Values:  <string>
Command Line:    filter_issuer_org

‍Description

Filters certificates based on the Organization (O) of the issuing CA, useful for identifying certificates from particular authorities.

filter_subject_ou

Purpose:         Specifies filter logic for certificates based on the organizational unit (OU) in the subject field.
Allowed Values:  <string>
Command Line:    filter_subject_ou

‍Description

Filters certificates based on the Organizational Unit (OU) in the subject field, allowing selection based on department or team.

filter_issuer_ou

Purpose:         Specifies filter logic for certificates based on organizational unit (OU) of the issuer.
Allowed Values:  <string>
Command Line:    filter_issuer_ou

‍Description

Filters certificates based on the Organizational Unit (OU) of the issuer, enabling classification by department or organizational structure.

filter_subject_s

Purpose:         Specifies filter logic for certificates based on the state (S) in the subject field.
Allowed Values:  <string>
Command Line:    filter_subject_s

‍Description

Filters certificates based on the State (S) in the subject field, grouping certificates by regional location.

filter_issuer_s

Purpose:         Specifies filter logic for certificates based on state (S) of the issuer.
Allowed Values:  <string>
Command Line:    filter_issuer_s

‍Description

Filters certificates by the State (S) of the issuing CA, useful for managing certificates issued from different regions.

‍

Section [paths]

This section covers the configuration options related to file and directory paths used by the system for storing and managing certificates, keys, logs, and other essential security assets. Properly defining these paths ensures a well-structured and secure environment for certificate lifecycle management. The following options allow customization of storage locations for certificates, keys, encryption tokens, logs, and trusted certificate authorities (CAs).

certificate_path

Purpose:                    Specifies the folder for storing newly enrolled or renewed certificates.
Allowed Values:              <path_to_folder>
Default Value for Windows:   .\
Default Value for Linux:     ./
Command Line:                certificate_path

‍Description

The certificate_path option specifies the directory where newly enrolled or renewed certificates will be stored. This ensures that all issued certificates are saved in a structured and organized manner, making them easily accessible for applications or services that require them. By default, the certificates are stored in the current working directory (.\), but a custom path can be set to align with system security policies and operational requirements. Example: C:\path\to\folder

certificate_format

Purpose:         Defines the format in which certificates are saved.
Allowed Values:  pfx | pem | p12 | crt | cer | p7b
Command Line:    certificate_format

‍Description

The certificate_format option defines the file format used when saving certificates. Various formats are available to support different applications and security requirements.

• pfx and p12 are commonly used for storing private keys along with the certificate in a single encrypted file.
• pem is a base64-encoded format typically used in UNIX-based systems.
• crt and cer are standard formats for storing public certificates.
• p7b is often used for certificate chains.

Choosing the correct format ensures compatibility with the target system and applications that will use the certificate.

privatekey_path

Purpose:                     Specifies the folder for storing encrypted private keys.
Allowed Values:              <path_to_folder>
Default Value for Windows:   .\
Default Value for Linux:     ./
Command Line:                privatekey_path

‍Description

The privatekey_pathoption defines the directory where encrypted private keys are stored. Private keys are critical security assets and should be kept in a secure location with restricted access to prevent unauthorized use. By default, they are stored in the current working directory (.\), but it is recommended to use a dedicated, protected directory. Proper access controls and encryption should be enforced to maintain confidentiality and integrity.

publickey_path

Purpose:                     Specifies the folder for storing public keys.
Allowed Values:              <path_to_folder>
Default Value for Windows:   .\
Default Value for Linux:     ./
Command Line:                publickey_path

‍Description

The publickey_path option specifies the directory where public keys are stored. Public keys are typically shared with other entities for encryption and signature verification purposes. Keeping public keys in a dedicated location ensures they are easily accessible when needed for secure communications. While public keys do not require the same level of protection as private keys, maintaining proper organization improves security management.

encryptiontoken_path

Purpose:                     Specifies the folder for storing encryption tokens.
Allowed Values:              <path_to_folder>
Default Value for Windows:   .\
Default Value for Linux:     ./
Command Line:                encryptiontoken_path

‍Description

The encryptiontoken_path option defines the directory where encryption tokens are stored. These tokens may be used to protect private keys, provide authentication, or facilitate encrypted operations within the system. Proper security controls should be implemented to ensure that encryption tokens remain confidential and are not exposed to unauthorized users. Storing these tokens in a secure, access-restricted directory minimizes the risk of misuse.

log_path

Purpose:                     Specifies the folder for storing log files.
Allowed Values:              <path_to_folder>
Default Value for Windows:   .\
Default Value for Linux:     ./
Command Line:                log_path

‍Description

The log_path option specifies the directory where log files related to certificate enrollment, renewal, and validation are stored. Logs are essential for auditing, troubleshooting, and monitoring system behavior. Keeping logs in an accessible but secure location allows administrators to review operations and identify potential issues.

trusted_system_ca

Purpose:         Specifies the trusted certificate authorities (CA) configured within the system.
Allowed Values:  yes | no
Default Value:   no
Command Line:    trusted_system_ca

‍Description

The trusted_system_ca option determines whether the system’s built-in trusted certificate authorities (CAs) should be used.

• yes
‍Enables the use of the system's pre-configured trusted CA list.
• no
Disables this feature, requiring explicitly specified trusted CA paths.

Enabling system-trusted CAs simplifies certificate validation but may introduce risks if the system contains outdated or compromised CAs.

trusted_ca_paths

Purpose:         Specifies the file path or directory where trusted certificate authorities (CA) are stored.
Allowed Values:  <path_to_folder>
Command Line:    trusted_ca_paths

‍Description

The trusted_ca_paths option specifies the directory or file path where trusted Certificate Authorities (CAs) are stored. This allows users to define custom CA locations rather than relying on system defaults.

• Multiple paths can be specified using the | separator.
• Root paths are not allowed to prevent unintended exposure of certificate files.

This option is useful for organizations managing their own CA hierarchy or needing to trust certificates from specific external authorities.

Example for Windows:

• C:\trusted_cas\
• C:\root_ca|D:\certificates

Example for Linux:

• /etc/ssl/certs
• /etc/ssl/certs|/usr/local/share/ca-certificates

‍

Section [names]

This section defines the naming conventions for various cryptographic files generated during the certificate enrollment and renewal process. Proper naming conventions ensure that files are uniquely identifiable, making it easier to manage and track certificates, keys, and encryption tokens across different systems.

Placeholders such as <hostname> and <id> are used to generate unique filenames dynamically.

General rules:

• <hostname> represents the computer’s hostname, ensuring that filenames are associated with a specific machine.
• <id> is a randomly generated string that provides uniqueness, preventing conflicts between multiple files.
• An asterisk (*) in the allowed values indicates that any arbitrary filename is permitted.

certificate_name

Purpose:         Specifies the name format for newly enrolled or renewed certificate.
Allowed Values:  *.cer | *.crt | *.p7b | *.pem | *.pfx | *.p12
Default Value:   <hostname>_<id>.pfx
Command Line:    certificate_name

‍Description

The filename includes the hostname and a randomly generated identifier to ensure uniqueness. Different file extensions correspond to various certificate formats, such as .pfx for PKCS#12 containers or .pem for base64-encoded certificates.

publickey_name

Purpose:         Specifies the name format for public key.
Allowed Values:  *.pub
Default Value:   <hostname>_<id>.pub
Command Line:    publickey_name

‍Description

Defines the naming convention for public key files. The format ensures that the public key is uniquely identified by incorporating the hostname and a random identifier, which is useful for systems managing multiple key pairs.

privatekey_name

Purpose:         Specifies the name format for private key.
Allowed Values:  *.key
Default Value:   <hostname>_<id>.key
Command Line:    privatekey_name

‍Description

The generated private key will be stored with a name that includes the hostname and a unique identifier, ensuring clear differentiation between multiple private keys on the same system.

encryptiontoken_name

Purpose:         Specifies the naming convention for files containing the token for private key encryption.
Allowed Values:  *.txt
Default Value:   <hostname>_<id>.txt
Command Line:    encryptiontoken_name

‍Description

These tokens are essential for securing private keys and ensuring they are accessible only to authorized users. The filename format helps in identifying the correct encryption token for a specific system and key.

‍

CERIAL Quick Start (Linux and Windows)

Welcome to CERIAL, BxC’s Certificate Management tool for automating the certificate lifecycle on your endpoints!

This quick start guide covers everything for a ramp-up start of our solution for Linux and Windows operating systems to manage certificates on your system.

‍

Purpose Of This Guide

This guide serves as a comprehensive resource designed to ease the understanding and implementation of certificate management processes using our CERIAL solution. It will enable users to seamlessly enroll and renew certificates on their devices, ensuring secure and authenticated communication within networks.

What is Certificate Management?

Certificate Management refers to the process of creating, storing, protecting, and managing digital certificates, to secure and authenticate communication between devices, services, and users within networks. Efficient certificate management is crucial to support the confidentiality, integrity, and availability of information within an organization.

Why Automate?

Automating certificate management offers many benefits:

• Efficiency: Automation streamlines certificate lifecycle processes, reducing manual intervention and saving time. 
• Risk mitigation: Automated systems help prevent costly downtime by ensuring well-timed certificate renewals and reducing the risk of expired certificates.
• Resource optimization: Automation saves resources and effort by efficiently managing the installation and maintenance of certificates.

Why Use CERIAL?

Effective Certificate Management is vital:

• Ensures security: Helps in securing communication between devices and applications and prevents unauthorized access, thereby supporting data confidentiality and integrity.
• Builds trust: Proves a trust relationship between communicating entities, enabling them to trust the identity of each other.
• Prevents downtime: Regular renewal and proper management of certificates help in avoiding service disruptions due to expired certificates.
• Compliance: Helps in meeting organizations’ internal and external regulatory requirements related to data protection and information security.

Overview Of CERIAL

The CERIAL solution is a versatile and user-friendly tool designed to simplify the certificate management process, enabling users to efficiently enroll and renew certificates on their devices.

Main Functions Of CERIAL

• Certificate inventory management: CERIAL performs fully automated searches within the device's certificate store to find digital certificates. Its configuration involves defining search criteria, enabling users to specify how CERIAL behaves during the search process.
• Initial enrollment: The tool enables to generate and send a certificate signing request (CSR) to an enrollment server, which then validates the CSR and its compliance with RFC 7030 and issues the corresponding certificate.
• Renewal: It allows to automate the renewal of stored certificates before expiration, supporting continuous security and trust relationships.

Who Should Use This Guide?

This guide is intended for:

• Device admins: Responsible for configuring the CERIAL tool and managing the configuration files, including settings related to enrollment, renewal, and revocation of certificates.
• Device users: Using devices where CERIAL is deployed and using the digital certificates managed by CERIAL on such devices.
• IT security professionals: Anyone involved in supporting the security posture of an organization can receive help from understanding and implementing the processes described in this guide.

How To Use This Guide

• Start by understanding the pre-requisites and ensuring that the necessary conditions are met before going ahead with the processes.
• Follow the step-by-step guide corresponding to the operating system of your device.
• Refer to the troubleshooting section for solutions to common issues.
• For further detailed information on how to configure and use the CERIAL you can check the online reference manual.
• Use the contact information provided in case of unresolved issues or added support requirements.

‍

‍

Linux Step-by-step Guide

‍

System Requirements

A Linux distribution with kernel 2.6 or later is required. It is recommended to use kernel 3.10.

CERIAL supports glibc and musl based systems.

It is recommended to use a non-privileged user since CERIAL does not need root access in general.

Private keys will be stored on the file system. Please take care of confidentiality of all used paths.

settings.ini File Configuration

Copy the example configuration file settings.ini from the downloaded package into same folder of CERIAL. Then you can edit the example configuration file.

Here is the most basic example of the settings.ini file:

[general]
opmode=init
storetype=filestore
[enrollserver]
enroll_endpoint=https://pgw.bxc-technology.de:8443/pgwy/est/simpleenroll
[csr]
csr_cn=client.bxc-technology.de
csr_org=BxC Security
csr_ou=OT PCs
csr_country=DE
csr_san=dns:client.bxc-technology.de
[certinfo]
validate_tls_certificate_chain=no
validate_tls_certificate=no
[paths]
certificate_path=$PWD
privatekey_path=$PWD

For a successful run at least the enroll_endpoint must be adjusted, and EST server must use the HTTPS protocol.

Change it from https://pgw.bxc-technology.de:8443/pgwy/est/simpleenroll to your EST server’s URL.

No EST Server?

If you do not have an EST server in your infrastructure yet, please reach out to us. We are happy to provide you with a test URL, from which you can get test certificates to get a feeling on the ease of managing certificates via EST. Those certificates are only short-lived and shall not be used for productive use!

Write us an email to: cerial@bxc-security.com.

Execute CERIAL

There is no specific installation routine needed, as the tool is provided as a self-executable program. If you are using an endpoint protection solution, you may need to allow the execution of CERIAL, depending on your security policies.

Note: CERIAL does not make any directories by itself.

Extracting The Archive

• Start a shell as non-privileged user.
• The binary is part of a tarball, you can extract it with tar:
  • Example for GNU tar: tar -x -f cerial.tar

Configure Permissions And Directories On Linux

To ensure that the CERIAL solution operates correctly on Linux, it is essential to configure permissions for specific directories. These permissions are focused on certificate and private key directories, trusted root certificates and encrypted private key access.

Permission For Trusted Root Certificates And Sensitive Data:

In general, “access” in the context for Linux means that the process that wants to access data stored on a file system is allowed to do a read, write or execution action. A Linux file system configures the access rights by setting the ACL permissions for files and folders. In addition, a Linux security module can restrict the access to data stored on a file system.

• If private keys are stored encrypted, provide execute and write permissions for the folder holding the encryption token only for dedicated users.
• If private keys are stored unencrypted, it is sufficient to reduce the access rights to the path of the private keys for least privileges.
• If the trusted CA certificates path is used, the user must have read access to the certificates stored in the path.

Successful Run Of CERIAL

In the following there is an example of having CERIAL configured with the goal of doing an initial enrollment and saving the issued certificate on the file system.

• Start a shell. It is recommended to use a non-privileged user to run the shell.
• Change to the directory where cerial is placed. (e.g.: cd /path/to/CERIAL)
• Run cerial with the following two arguments:
  • --settings will take the path to the setting.ini file
  • --credentials will take the username and password for the HTTP basic authentication; the format must be: <USERNAME>:<PASSWORD>

Example console output of a CERIAL run:

If the run was successful, you can see the result of the issued certificate by reading the certificate.

Example Of A Successful Run Of CERIAL Focusing On Paths

In this example, we are using the existing paths in the settings.ini file. Please be aware that paths should be already created.

Here is an example of settings.ini file which includes the [paths] as well. The paths mentioned below (the last 5 lines) should exist to have a successful run with CERIAL.

[general]
opmode=init
storetype=filestore
[names]
encryptiontoken_name=client.bxc-technology.de.<id>.txt
[enrollserver]
enroll_endpoint=https://pgw.bxc-technology.de:8443/pgwy/est/simpleenroll
[csr]
csr_cn=client.bxc-technology.de
csr_org=BxC Security
csr_ou=OT PCs
csr_country=DE
csr_san=dns:client.bxc-technology.de
[certinfo]
validate_tls_certificate_chain=no
validate_tls_certificate=no
[paths]
log_path=/path/to/CERIAL/logs
certificate_path=/path/to/CERIAL
privatekey_path=/path/to/CERIAL
encryptiontoken_path=/path/to/CERIAL

‍

Windows Step-By-Step Guide

‍

System Requirements

Windows 10 or 11

• Administrator privileges will be needed if you aim at managing certificates in the local system Windows certificate store. This store is protected for system and administrative users of the system only.
• Without administrator privileges, you can manage certificates in the respective user’s Windows certificate store, which is used to execute the program.
• Independent of the privileges it is also possible to use the filesystem as certificate store. Then write access to the path of the certificate store is needed.
• No further runtime environment or 3rd party library is needed.

settings.ini file Configuration

Copy the example configuration file settings.ini from the downloaded package into the execution folder of CERIAL. Then you can edit the example configuration file.

Here is the most minimalistic example of the settings.ini file:

[general]
opmode=init
storetype=user
[enrollserver]
enroll_endpoint=https://pgw.bxc-technology.de:8443/pgwy/est/simpleenroll
[csr]
csr_cn=client.bxc-technology.de
csr_org=BxC Security
csr_ou=OT PCs
csr_country=DE
csr_san=dns:client.bxc-technology.de
[certinfo]
validate_tls_certificate_chain=no
validate_tls_certificate=no

For a successful run at least the enroll_endpoint must be adjusted.

Change it from https://pgw.bxc-technology.de:8443/pgwy/est/simpleenroll to your EST server’s URL. The EST server must use the HTTPS protocol.

No EST Server?

If you do not have an EST server in your infrastructure yet, please reach out to us. We are happy to provide you with a test URL, from which you can get test certificates to get a feeling on the ease of managing certificates via EST. Those certificates are only short-lived and shall not be used for productive use!

Write us an email to: cerial@bxc-security.com.

Execute CERIAL

There is no specific installation routine needed, as the tool is provided as a self-executable program. If you are using an endpoint protection solution, you may need to allow the execution of CERIAL, depending on your security policies.

Windows 10 and 11

‍

• Start the command line within the desired context.
  • If CERIAL shall manage the local system Windows certificate store, the tool must run with local administrator privileges.

‍

• If you plan to let CERIAL manage the Windows certificate store of a specific user account, it must be run in the context of that user account.

Successful Run Of CERIAL

In the following there is an example of having CERIAL in the CMD configured with the goal of doing an initial enrollment and saving the issued certificate in the Windows certificate store of the current user.

• Start CMD within the context of the current user. (Open Command Prompt)
• Change to the directory where cerial.exe is placed. (e.g.: cd C:\CERIAL)
• Run cerial.exe with the following two arguments:
  • --settings will take the path to the setting.ini file
  • --credentials will take the username and password for the HTTP basic authentication; the format must be: <USERNAME>:<PASSWORD>

‍

Example console output of a CERIAL run:

‍

If the run was successful, you can see the result of the issued certificate within the Windows certificate manger certmgr.msc:

Advanced Run Of CERIAL

In this step a folder named "logs" should be created.

‍

Here is an example of settings.ini file which holds the [paths] as well. The paths mentioned below (the last 5 lines) should exist to have a successful run with CERIAL.

[general]
opmode=init
storetype=filestore
[names]
encryptiontoken_name=client.bxc-technology.de.<id>.txt
[enrollserver]
enroll_endpoint=https://pgw.bxc-technology.de:8443/pgwy/est/simpleenroll
renew_endpoint=https://pgw.bxc-technology.de:8443/pgwy/est/simpleenroll
[csr]
csr_cn=client.bxc-technology.de
csr_org=BxC Security
csr_ou=OT PCs
csr_country=DE
csr_san=dns:client.bxc-technology.de
[certinfo]
validate_tls_certificate_chain=no
validate_tls_certificate=no
[paths]
log_path=C:\CERIAL\logs
certificate_path=C:\CERIAL
privatekey_path=C:\CERIAL
encryptiontoken_path=C:\CERIAL

‍

After having successful runs, if the mentioned folders exist, you are expected to see different log files in the specified log_path as it is shown in the following screenshot. This is valid for all paths (e.g. encryptiontoken_path).

‍

Running CERIAL

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

cerial.exe (--help | -h)

Displays the manual with common available options provided by CERIAL. For more extensive explanation, use this online documentation.

cerial.exe (--version | -v)

Displays the version of CERIAL you are currently running.

cerial.exe (--show) [--settings=<path_to_settings>]

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. The program stops after showing the configuration, it is not performing any certificate actions in this mode.

cerial.exe [--settings=<path_to_settings_file>] [--logging=<path_to_logging_folder>] [--credentials=<basic_authentication>]

This is the normal run mode. The most important settings for the command line are listed here:

• --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.
• --credentials=<username:password> - If you protect your EST enrollment endpoint with basic authentication credentials, you can provide them on the command line. Because basic authentication, especially for EST, are only required during the initial rollout of a certificate, this should be provided only via the command line and not persistently stored in the config file, while this is technically still possible.

‍

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.

‍

Exit CERIAL

Once CERIAL completes its operations, it provides exit codes that indicate the status of the process. These exit codes help users understand whether CERIAL executed successfully or encountered errors. Additionally, if the user configures CERIAL to trigger a post-run program, CERIAL shares relevant exit information with that program to facilitate the continuation of the certificate lifecycle process in the target application.

Exit Codes

This section details the exit codes, their corresponding reasons, and how to interpret them in different command-line environments.

Exit codes in CERIAL are grouped into different categories based on their nature. Users must be aware of the correct way to retrieve the exit code, depending on the operating system and the shell or command-line environment.

‍

Windows

In Windows environments, exit codes can be retrieved using the appropriate command for the execution environment:

• CMD (Command Prompt): Use %ERRORLEVEL%
• PowerShell: Use $LASTEXITCODE

Linux

On Linux systems, the method for retrieving exit codes depends on the shell in use:

• For Bourne Shell variable is $?
• For C Shell variable is $status

‍

Exit codes in Linux and Windows are structured similarly, providing detailed feedback on the execution state of CERIAL. The following sections outline each category of exit codes and their meanings.

0

Description:    CERIAL executed without interruptions and completed all tasks successfully.
Error Code:     0
Cluster:        Successful

100

Description:    The operating system is not supported. CERIAL must be run on a compatible platform
Error Code:     100
Cluster:        Environment

101

Description:    The cryptographic library failed to initialize, possibly due to missing system dependencies or incorrect configuration.
Error Code:     101
Cluster:        Environment

102

Description:    CSR generation failed in renewal mode (opmode=renew). Possible causes include incorrect CSR settings, missing required fields, or insufficient system permissions.
Error Code:     102
Cluster:        Environment

103

Description:    The enrollment server returned an error message, which could be due to connectivity issues, server misconfiguration, or authentication failures.
Error Code:     103
Cluster:        Environment

104

Description:    CSR generation failed in auto mode (opmode=auto). This may be caused by invalid CSR parameters, system permission issues, or missing required fields.
Error Code:     104
Cluster:        Environment

105

Description:    The enrollment server returned an error while operating in auto mode (opmode=auto). Possible reasons include incorrect credentials, unreachable servers, or misconfigured certificate issuance policies.
Error Code:     105
Cluster:        Environment

200

Description:    The log file could not be saved. This may occur due to an inaccessible directory, write permission restrictions, or a full disk.
Error Code:     200
Cluster:        Log file

201

Description:    The log file could not be moved to the specified path, potentially due to incorrect path settings or insufficient write permissions.
Error Code:     201
Cluster:        Log file

202

Description:    The log file could not be renamed, likely because another process is using the file or there is a file name conflict.
Error Code:     202
Cluster:        Log file

300

Description:    The logging system could not be initialized. This can be caused by incorrect log configuration or system-level errors.
Error Code:     300
Cluster:        Others

301

Description:    No certificate was issued because CSR generation, enrollment, or certificate storage failed. Possible causes include an unreachable enrollment server or an invalid CSR request.
Error Code:     301
Cluster:        Others

302

Description:    The selected "opmode" is not supported. Ensure that the configuration is using a valid and supported operation mode.
Error Code:     302
Cluster:        Others

400

Description:    The selected certificate store is not supported. Ensure the storage type is correctly configured (user, system, or file).
Error Code:     400
Cluster:        Configuration

401

Description:    The certificate was not imported after a successful enrollment. This may be due to an inaccessible or incorrectly configured certificate store.
Error Code:     401
Cluster:        Configuration

402

Description:    The certificate was not imported in auto mode (opmode=auto). This issue may be caused by an unsupported store type or incorrect configuration.
Error Code:     402
Cluster:        Configuration

500

Description:    The configuration file could not be parsed, likely due to syntax errors or missing parameters.
Error Code:     500
Cluster:        User

501

Description:    The certificate store could not be initialized, possibly due to an unsupported store type or misconfigured access settings.
Error Code:     501
Cluster:        User

502

Description:    The EST URL or credentials are not defined in initialization mode (opmode=init). Ensure that the correct URL and authentication details are provided.
Error Code:     502
Cluster:        User

503

Description:    The EST URL or credentials are not defined in renewal mode (opmode=renew). Verify that the required authentication details are configured.
Error Code:     503
Cluster:        User

504

Description:    The EST URL or credentials are not defined in auto mode (opmode=auto) when issuing an initial certificate. Check the configuration for missing authentication parameters.
Error Code:     504
Cluster:        User

505

Description:    The EST URL or credentials are not defined in auto mode (opmode=auto) when performing a certificate renewal. Ensure that valid credentials are specified in the configuration.
Error Code:     505
Cluster:        User

‍

Post-Run Handover

(Enterprise feature)

‍

Introduction

‍

CERIAL supports executing an external script or program after completing its process. This feature enables seamless integration with target applications by informing external programs about the execution results, including issued certificates, keys, and any potential issues encountered during the process.

The external program can then:

• Process and activate the newly enrolled or renewed certificates.
• Handle error conditions by reporting them to logging systems, Security Information and Event Management (SIEM) solutions, or operational monitoring consoles.

To facilitate this integration, CERIAL generates a JSON structure containing relevant execution details. Attributes are only included if applicable to the execution result and contain meaningful information. For example, the attribute issued_certificate_serial_hex will only be present if a certificate has been successfully issued.

The following table describes the attributes included in the JSON structure.

JSON Attributes

exit_code

Description:    The exit code shared by CERIAL as described in chapter "Exit Codes".
Attribute:      exit_code
Type:           number

‍Description

This attribute represents the overall result of CERIAL’s execution as a numerical code. It provides a direct indication of whether the process completed successfully or encountered an issue. The exit code allows external systems to interpret the execution result programmatically and respond accordingly.

exit_message

Description:    A human-readable message describing the execution outcome, making it easier to integrate with central log management or SIEM solutions.
Attribute:      exit_message
Type:           string

‍Description

A descriptive message providing additional context about the execution outcome. This message helps administrators and monitoring systems understand the result in human-readable terms. It is particularly useful for logging and debugging purposes, as it supplements the exit code with meaningful explanations.

issued_certificate_serial_hex

Description:    Hexadecimal representation of the issued certificate’s serial number.
Attribute:      issued_certificate_serial_hex
Type:           string

Description

This attribute contains the serial number of the issued certificate in hexadecimal format. Hexadecimal representation is commonly used in cryptographic applications and helps in compatibility with various tools and systems that rely on this format for certificate identification.

issued_certificate_serial_number

Description:    Decimal representation of the issued certificate’s serial number.
Attribute:      issued_certificate_serial_number
Type:           number

Description

This attribute provides the serial number of the issued certificate in decimal format. Some applications require certificate serial numbers in decimal rather than hexadecimal, making this attribute essential for ensuring compatibility with different processing systems.

issued_certificate_path

Description:    Filesystem path to the issued certificate file (public key only).
Attribute:      issued_certificate_path
Type:           string

Description

This attribute specifies the filesystem location where the issued certificate file is stored. The path points to the public key portion of the certificate, which can be used for further processing, deployment, or verification.

issued_privatekey_path

Description:    Filesystem path to the private key associated with the issued certificate. This is only applicable if the certificate was stored in the filesystem.
Attribute:      issued_privatekey_path
Type:           string

Description

This attribute indicates the filesystem location of the private key associated with the issued certificate. The attribute is only included if private key storage is enabled. Access to this file should be strictly controlled, as it contains sensitive cryptographic material.

issued_encryptiontoken_path

Description:    Filesystem path to the private key encryption password file, applicable only if private key protection was enabled.
Attribute:      issued_encryptiontoken_path
Type:           string

Description

This attribute provides the filesystem path to a password file containing the encryption token used to protect the private key. The attribute is present only if private key encryption is enabled. The file contains a randomly generated password to facilitate private key decryption. The token ensures that the private key remains secure and can only be accessed by authorized processes.

issued_certificate_subject_dn

Description:    Subject Distinguished Name (DN) of the issued certificate.
Attribute:      issued_certificate_subject_dn
Type:           string

Description

This attribute contains the Distinguished Name (DN) of the certificate subject. The DN uniquely identifies the entity to which the certificate was issued. It typically includes components such as Common Name (CN), Organization (O), and Country (C), following X.500 naming conventions.

issued_certificate_issuer_dn

Description:    Issuer Distinguished Name (DN) of the issued certificate.
Attribute:      issued_certificate_issuer_dn
Type:           string

Description

This attribute provides the Distinguished Name (DN) of the Certificate Authority (CA) that issued the certificate. It is used to identify the certificate’s trust chain and verify its authenticity. The DN follows the X.500 standard and helps in certificate validation.

Example

Here you can find an example of the JSON body that is handed over to the post-run executable or script.

{
  “exit_code”:0,
  “exit_message”:"",
  “issused_certificate_serial_number”:12345678
  “issued_certificate_path”:“/mnt/pki/new/webserver_cert.cer”,
  “issued_privatekey_path”:“/mnt/pki/priv/new/webserver_cert.key”,
  “issued_ encryptiontoken _path”:“/mnt/secret/webserver_cert.pass”,
  “issued_certificate_ subject_dn”:“CN=App-SRV,O=Company,C=DE”,
  “issused_certificate_issuer_dn”:“CN=Server Issuing CA 1, O=Company, C=DE”
}

‍