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)
-
API Client Provider ID
-
API Client secret
-
-
End-Entity credentials (created and retrieved by MTG-CLM’s UI)
-
End-Entity ID
-
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
Name | Required | Default | Description |
---|---|---|---|
-c, --config-dir |
false |
|
This option allows the definition of a custom configuration directory. If not set, the default directory of |
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
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 Example: |
-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.
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
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 |
--csr |
false |
- |
Full path to the certificate signed request file used with PKCS 10 mode. |
--output-type |
false |
|
The type of the generated files. Allowed values are: |
--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 |
|
The named curve property. |
--eddsa-curve |
false |
|
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.
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.
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. |
3.5.1. 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 Example: |
--no-proxy |
false |
|
Configure the scan to not use a proxy. |
--import-batch-size |
false |
|
The batch size for the import. |
--create-cert |
false |
|
Configure if the certificates for the imported requests should be created automatically in the CLM. |
--save-cert |
false |
|
Configure if the imported certificates should be saved in the file system under the configuration directory of the application. |
ers configure-scan
--servers "mail.example.com,web.example.com"
--ports "8443,9443"
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
Name | Required | Default | Description |
---|---|---|---|
--server |
false |
- |
The host and port for the LDAP server. Example: If no port is set, the default ports for the protocols |
-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:
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= |
----search-filter |
false |
- |
The search filter for the entries which contain the certificates. It must be enclosed with brackets. Example: |
--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. |
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
Port Number | Service |
---|---|
465 |
SMTP |
636 |
LDAP |
853 |
DNS |
989 |
FTP |
990 |
FTP |
992 |
Telnet |
993 |
IMAP |
995 |
POP |
3.7.2. 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 |
|
Enables the network scan. |
--scan-ctlog |
false |
|
Enables the ctlog scan. |
--scan-ldap |
false |
|
Enables the ldap scan. |
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.
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. |
ers -V
ers --help
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.
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 |
tlsVersion |
TLSv1.2 |
The version of the TLS protocol to use in the connection to the target machine. Valid values are |
timeoutSeconds |
60 |
An integer value specifying the seconds to time out the connection the target machine. |
ersIdProviderTlsProperties:
trustStorePath: "C:\\home\\path-to-truststore\\truststore.jks"
trustStorePassword: "password"
trustStoreType: "PKCS12"
tlsVersion: "TLSv1.2"
timeoutSeconds: 120