ERS CLI

1. Introduction

The ERS CLI is an implementation of a command line interface client that integrates with MTG Certificate Lifecycle Manager Server.

2. MTG-CLM integration

To enable integration with MTG-CLM, MTG Certificate Lifecycle Manager Server uses some information which could be created and retrieved using MTG-CLM UI and/or OpenID Connect provider. More specifically:

  • API Client credentials (created and retrieved by MTG-CLM’s UI or OpenID Connect Provider)

    1. API Client Provider ID

    2. API Client secret

  • End-Entity credentials (created and retrieved by MTG-CLM’s UI)

    1. End-Entity ID

    2. End-Entity secret

  • Policy ID (created and retrieved by MTG-CLM’s UI, policy should have "Imports Allowed" option set to true)

  • Base URL of MTG-CLM

  • Base URL of OpenID Connect Provider

If the connection with the MTG-CLM should be achieved through TLS, some more information is necessary:

  • Path of the appropriate truststore file

  • Password of the respective truststore

3. Commands

The following commands are supported by the ERS cli.

3.1. Ers

The ers command is the parent command of MTG Certificate Lifecycle Manager Server. It is used in front of every other command. Using this command the user can optionally set the location of the configuration file of MTG Certificate Lifecycle Manager Server.

3.1.1. Arguments

Table 1. Ers command arguments
Name Required Default Description

-c, --config-dir

false

${USER_HOME}/.ers

This option allows the definition of a custom configuration directory. If not set, the default directory of ${USER_HOME}/.ers will be used. It is used to persist configuration and state files between executions.

3.2. Login

The login command is used to establish the connection to the MTG-CLM and authenticate the MTG Certificate Lifecycle Manager Server against the Open ID Connect provider. The subsequent commands will use the specified credentials to authenticate the MTG Certificate Lifecycle Manager Server. To update the specified credentials, the user has to reuse the login command.

3.2.1. Arguments

Table 2. Login command arguments
Name Required Default Description

-u, --username

true

-

A string value corresponding to the api client provider ID.

-s

false

-

Provide this option to store the api client secret in the configuration file.

-p

true

-

The api client secret.

-e

true

-

A string value corresponding to the base URL of the MTG-CLM.

-o

true

-

A string value corresponding to the base URL of the Open ID Connect provider.

-x

false

-

A string value specifying the proxy server and port for the CLM server. This value must be given without http:// or https://. The server part is separated from the port part by using :.

Example: example.com:8080

-t, --truststore-path

false

-

The absolute path to the truststore which contains the trusted certificates necessary to validate the TLS connections to MTG-CLM and OpenID Connect provider.

-tp, --truststore-password

false

-

The password of the truststore which contains the trusted certificates necessary to validate the TLS connections to MTG-CLM and OpenID Connect provider.

An example for the use of the login command is shown in Listing 1.

Listing 1. Example for the use of login command
ers login -u 1513630e-6105-43c8-93c9-5b7f4daad353 \
    -s -p base64EncodedPass -e https://ers.example.com \
    -o https://openid.example.com/auth/realms/mtg-ers
    -x example.com:8080

3.3. Certificate request

The certificate request command is used to automate the certificate creation process. It provides various modes for generating certificates and exporting the generated files.

3.3.1. End entity authentication

To successfully run a certificate request command, you need to authenticate against MTG-CLM, using end entity credentials. The credentials for this type of authentication can be obtained by creating an end entity and an associated end entity password. More details can be found in [MTGClmUserManual]. During the certificate creation process, the policy used is the one associated with the end entity password. The certificate is issued for the end entity associated with the aforementioned credentials.

Certificate creation for policies that require manual approval or email verification is not supported yet.

3.3.2. Certificate request modes

The MTG Certificate Lifecycle Manager Server supports three different modes for generating new certificates. Specifically:

SERVER GENERATED

The user specifies the details of the certificate, and the MTG Certificate Lifecycle Manager Server sends a certification request to MTG-CLM. Next, the MTG-CLM generates a keypair and issues a certificate based on the specified certificate details. The client receives a keystore file containing the aforementioned files.

CLIENT GENERATED

The user specifies the details of the certificate. The MTG Certificate Lifecycle Manager Server generates a keypair and along with the user requirements, it creates a PKCS 10 request. The client sends this PKCS 10 request to MTG-CLM. Next, the MTG-CLM processes the request, the CA issues the certificate and the CLM sends it to the client.

PKCS 10 REQUEST

The user specifies the path to a valid PKCS 10 request. The client sends this PKCS 10 request to MTG-CLM. Next, the MTG-CLM processes the request, the CA issues the certificate and the CLM sends it to the client.

3.3.3. Arguments

Table 3. Certificate request command arguments
Name Required Default Description

--ee-uuid

true

-

The end entity id used in basic authentication.

--ee-password

true

-

The end entity password used in basic authentication.

-m or --mode

true

-

Specifies the mode of the certificate creation process. Possible values are SERVER_GENERATED, CLIENT_GENERATED, PKCS10, or RA_MODE.

--csr

false

-

Full path to the certificate signed request file used with PKCS 10 mode.

--output-type

false

PKCS12

The type of the generated files. Allowed values are: PKCS12, JCEKS, PEM, or DER.

--key-file

false

-

Full file name of the exported keystore file (absolute path + filename).

--key-file-password

false

-

The password used for the protection of the exported keystore file. For the output type PEM or DER, this option is not allowed. The PEM or DER file for the private key is stored without password protection.

--cert-file

false

-

Full file name of the exported certificate file (absolute path + filename).

--valid-for

false

One year

The period during which the certificate will be valid.

--algorithm

true

-

The crypto algorithm to be used during certificate creation process.

--rsa-key-size

false

2048

The RSA key size property.

--exponent

false

-

The exponent property.

--named-curve

false

brainpoolP256r1

The named curve property.

--eddsa-curve

false

curve25519

The EdDSA curve property.

--store

false

-

Automatically imports the certificate to Windows Certificate User Store (only for MS Windows system)

An example for the use of the certificate request command is shown in Listing 2.

Listing 2. Example for the use of certificate request command
ers certificate request -m SERVER_GEN \
    --ee-uuid 1513630e-6105-43c8-93c9-5b7f4daad353 \
    --ee-password eePassword --algorithm RSA \
    --key-file-password keystorePassword \
    --output-type PKCS12 \
    --key-file C:\Path\to\file\keystore.p12 \
    --store

3.4. Certificate status

The certificate status command is used to retrieve the status of the latest issued certificate. Specifically, the user can view the certificate ID, the IssuerDN and the expiration date of this certificate.

An example for the use of the status command is shown in Listing 3.

Listing 3. Example for the use of status command
ers certificate status

3.5. Configure-Scan

The configure-scan command is used to configure the servers, IPs, and ports in order to scan them for certificates later using the scan command. By using the --ctlog argument, it is also possible to import all public and available SSL certificates that the domain names given in the argument appear inside them. This uses the service crt.sh provided by Sectigo®. This command is required for the scan command to be prepared and work properly.

Each time configure-scan runs, previously configured values (servers, IPs, ports, ctlog) are getting replaced with the new ones.

An example for the use of the status command is shown in Listing 4, Listing 5.

3.5.1. Arguments

Table 4. Configure-scan command arguments
Name Required Default Description

--servers

true (false if ips or ctlog is given)

-

The servers/hostnames to scan for certificates

--ips

false

-

The IPs to scan for certificates. Works together only with the --servers or --ips arguments.

--ports

true (false if servers or ctlog are given)

-

The ports of the servers or IPs to scan for certificates.

--ctlog

true (false if servers or ips are given)

-

The domain names (comma separated) to import all public SSL certificates they appear inside.

--proxy

false

-

A string value specifying the proxy server and port for the CtLog scan. This value must be given without the http:// or https://. The server part is separated from the port part by using :.

Example: example.com:8080

--no-proxy

false

false

Configure the scan to not use a proxy.

--import-batch-size

false

10

The batch size for the import.

--create-cert

false

true

Configure if the certificates for the imported requests should be created automatically in the CLM.

--save-cert

false

false

Configure if the imported certificates should be saved in the file system under the configuration directory of the application.

Listing 4. Example for the configure-scan command using servers and ports
ers configure-scan
--servers "mail.example.com,web.example.com"
--ports "8443,9443"
Listing 5. Example for the configure-scan command using IPs and ports
ers configure-scan
--ips 198.51.100.0/24
--ports "8000-9000"
--ctlog "example.com,two.example.com"

3.6. Configure-LDAP

The configure-ldap command is used to configure the ActiveDirectory (AD) LDAP to scan them for certificates later using the scan command.

Each time configure-ldap runs, previously configured values are getting replaced with the new ones.

An example for the use of the status command is shown in Listing 6.

3.6.1. Arguments

Table 5. Configure-scan command arguments
Name Required Default Description

--server

false

-

The host and port for the LDAP server.

Example: proxy.example.com:8080

If no port is set, the default ports for the protocols ldap and ldaps will be used.

-t, --truststore-path

false

-

The absolute path to the truststore which contains the trusted certificates necessary to validate the TLS connections to the LDAP server.

-tp, --truststore-password

false

-

The password of the truststore which contains the trusted certificates necessary to validate the TLS connections to the LDAP server.

--auth-principal-name

false

-

The AD Principal Name of the user to use for LDAP requests in the form:

<LDAP user’s account name>@<domain name in upper case letters>

Example: ldap-user@EXAMPLE.COM

In AD this user must have read access to the LDAP entries

--auth-keytab

false

-

The location / path of the keytab file.

--auth-krb5conf

false

-

The location / path of the krb5.conf file.

--search-base-dn

false

-

The LDAP search baseDN in the form DC=<domain>,DC=<top level domain>

Example: DC=example,DC=com

----search-filter

false

-

The search filter for the entries which contain the certificates. It must be enclosed with brackets.

Example: (usercertificate=*)

--search-cert-attr

false

-

The attribute ID for the certificate.

--create-timestamp-attribute

false

-

The attribute ID for the creation timestamp.

--modified-timestamp-attribute

false

-

The attribute ID for the modification timestamp.

--page-size

false

1000

The page size for the LDAP search.

Listing 6. Example for the configure-scan command using servers and ports
ers configure-ldap
--server addc.example.com:636
--auth-principal-name  ldap-user@EXAMPLE.COM
--auth-keytab ldap.keytab
--search-base-dn  "DC=example,DC=com"
--search-filter (usercertificate=*)
--search-cert-attr usercertificate

3.7. Scan

The Scan command is used to scan the configured servers, ports, IPs and ctlog/domain names (configured by configure-scan command) for any SSL certificates. Then those certificates are sent and imported to the CLM server. Some ports mentioned below are always scanned by default. In addition, if enabled, the certificates scanned and imported are saved in the file system under the configuration directory of the application (see Table 1).

The policy passed as argument must allow the certificate import (set the appropriate field to true) so the certificates get imported into the server.

An example for the use of the status command is shown in Listing 7.

3.7.1. Default Ports

Table 6. The default ports scanned for certificates
Port Number Service

465

SMTP

636

LDAP

853

DNS

989

FTP

990

FTP

992

Telnet

993

IMAP

995

POP

3.7.2. Arguments

Table 7. Scan command arguments
Name Required Default Description

--policy-id

true

-

The UUID of the policy of CLM in which the imported certificates are attached.

--scan-network

false

true

Enables the network scan.

--scan-ctlog

false

true

Enables the ctlog scan.

--scan-ldap

false

true

Enables the ldap scan.

Listing 7. Example for the scan command
ers scan --policy-id e51cea73-3aa1-40a2-b21e-0d231b27d771

3.8. Help and Version support

All commands of MTG Certificate Lifecycle Manager Server provide help and version support by exposing two additional arguments. In case one of these arguments is specified in the command line arguments, MTG Certificate Lifecycle Manager Server prints the information corresponding to the specified command and then exits. The command is not executed.

Table 8. Help and version arguments
Name Required Default Description

-V, --version

false

-

Prints version information and exits.

-h, --help

false

-

Prints a help message for the specified command and then exits.

Listing 8. Example for the use of the version option
ers -V
Listing 9. Example for the use of the help option
ers --help
Listing 10. Example for the use of the help option for the login command
ers login -h

4. Configuration file

The configuration file is a yaml file that is used to hold records of the latest input arguments and acts as an alternative for specifying input arguments. The configuration file is by default created at the {app-dir} directory. The user can specify a different location for the configuration file using the ers command.

4.1. Specifying certificate request command arguments

For the certificate request command, a user can specify the input arguments from the configuration file instead of the command line. Sensitive information are stored as base64 encoded values. As a result, to configure the end entity ID and password in the configuration file, the user has to enter the base64 encoded values, accordingly. This functionality is not supported for all arguments. The following arguments are not recorded in the configuration file and thus must be specified explicitly in every command:

  • Certificate creation mode (-m)

  • Path to the certificate signed request (--csr)

  • All the file export arguments (--output-type, --keystore, --keystore-file, --keystore-password, --separate, --cert-output, --key-output)

Furthermore, the configuration file holds records of the login arguments (api client credentials in base64 encoding and base URLs). However, these arguments cannot be specified from the configuration file. It is mandatory for the user to specify them in every login command.

4.2. Holding records of certificate request command line arguments

When a user executes a certificate request command, the specified input arguments are stored in the configuration file. Thus, in a subsequent command, the user can omit the input of the arguments that remain the same. For example, the user has to specify the end entity credentials in the initial certificate request command only once. These credentials are stored in the configuration file and used in subsequent requests so that the user does not have to specify them every time. This way commands become less verbose. To use different credentials, the user needs to specify again the input arguments from the command line. The recorded values in the configuration file are updated accordingly. This functionality is not supported for all arguments, as described in the previous section.

If an argument is specified from the command line and also exists in the configuration file, the input value from the command line will override the value from the configuration file. Following the command execution, the configuration value will be updated with the new command line argument value.

4.3. SSL configuration

The configuration file contains the required parameters that are used to configure a TLS connection. More specifically, the configuration file contains two sections of parameters each one corresponding to a different TLS connection. The ersPkiApiTlsProperties section corresponds to the TLS connection to the MTG-CLM, while the ersIdProviderTlsProperties section corresponds to the TLS connection to the Open ID Connect provider. To use the MTG Certificate Lifecycle Manager Server in SSL mode, the user has to specify the appropriate TLS properties in the configuration file. These properties are initialized with default values as shown below.

Table 9. TLS configuration parameters
Name Default Description

trustStorePath

-

The location of a keystore file containing certificates that are used to verify the TLS connection to the target machine.

trustStorePassword

-

The password protecting the truststore.

trustStoreType

PKCS12

The format of the truststore. Valid values are JKS, JCEKS or PKCS12.

tlsVersion

TLSv1.2

The version of the TLS protocol to use in the connection to the target machine. Valid values are TLSv1.2 or TLSv1.3.

timeoutSeconds

60

An integer value specifying the seconds to time out the connection the target machine.

Listing 11. Example for configuring the Open ID Connect provider TLS properties
ersIdProviderTlsProperties:
  trustStorePath: "C:\\home\\path-to-truststore\\truststore.jks"
  trustStorePassword: "password"
  trustStoreType: "PKCS12"
  tlsVersion: "TLSv1.2"
  timeoutSeconds: 120