Certificate Configuration

The following API commands enable you to configure certificates on an SSL-configured Agent:

config server:agent:crt:expiration::get
config server:agent:csr::create
config server:agent:crt::deploy

config server:agent:crt:expiration::get

The config server:agent:crt:expiration::get command enables you to get the expiration date of an SSL certificate from an SSL-configured Agent. The date is returned exactly as it appears in the certificate.

This feature is offered in an environment with Control-M 9.0.20 or higher.

For information about using this API command in a script to automate certificate updates, see Automating SSL Certificate Updates on Control-M/Agents.

CLI Syntax

Copy

ctm config server:agent:crt:expiration::get <server> <agent>

The following table describes the config server:agent:crt:expiration::get command parameters.

Parameter	Description
server	Name of Control-M/Server.
agent	Name of Agent.

REST API Syntax

cURL:

Copy

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/config/server/$server/agent/$agent/crt/expiration"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

config server:agent:csr::create

The config server:agent:csr::create command enables you to create a certificate signing request (CSR) for an SSL-configured Agent.

This feature is offered in an environment with Control-M 9.0.20 or higher.

For information about using this API command in a script to automate certificate updates, see Automating SSL Certificate Updates on Control-M/Agents.

CLI Syntax

Copy

ctm config server:agent:csr::create <server> <agent> -f <configuration file>

To save the CSR output (a block of encoded text) in a file, you can append the following to the end of the CLI command: > fileName

The following table describes the config server:agent:csr::create command parameters.

Parameter	Description
server	Name of Control-M/Server.
agent	Name of Agent.
configuration file	JSON file that contains required parameters for the CSR. Here is an example for the content of this file: Copy `{ "organization": "example_organization", "organizationUnit": "example_unit", "cityLocality": "example_city", "stateProvince": "example_state", "country": "CO", "emailAddress": "admin@example.com" }` For country, use the two-letter code abbreviation of the country where your organization is located. For example, CO is Colombia. Note that the CN property is set automatically by the Agent. Do not include the CN property in this configuration file.

REST API Syntax

cURL:

Copy

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" -H "Content-Type: application/json"
--data "@examples\configuration.json"  "$endpoint/config/server/$server/agent/$agent/csr"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

To save the output in a CSR file, you can append the following to the end of the command:

Copy

-o $file_path$file_name

config server:agent:crt::deploy

The config server:agent:crt::deploy command enables you to deploy a signed certificate to an SSL-configured Agent. This is supported only if the signed certificate was created using the config server:agent:csr::create command . The new certificate that you deploy replaces the existing certificate.

For the new certificate to take effect after the deployment, recycle the Agent. If the new certificate was signed by a new CA, ensure that this CA is recognized also by the Control-M/Server.

This feature is offered in an environment with Control-M 9.0.20 or higher.

For information about using this API command in a script to automate certificate updates, see Automating SSL Certificate Updates on Control-M/Agents.

CLI Syntax

Copy

ctm config server:agent:crt::deploy <server> <agent> <crt_filepath> <ca_chain_filepath>

The following table describes the config server:agent:crt::deploy command parameters.

Parameter	Description
server	Name of Control-M/Server.
agent	Name of Agent.
crt_filepath	Full path to the certificate file.
ca_chain_filepath	Full path to the Certificate Authority (CA) chain file.

REST API Syntax

cURL:

Copy

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "$AuthHeader" -F "crtFile=@examples/crt.pem"
-F "caChainFile=@examples/ca_chain.pem" "$endpoint/config/server/$server/agent/$agent/crt"

To determine the correct AuthHeader value—"Authentication: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Automating SSL Certificate Updates on Control-M/Agents

As the administrator, you can automate updates to SSL certificates on multiple Control-M/Agents by incorporating the provided AAPI commands in scripts.

Below is an example of a method that involves two scripts for automating updates of SSL certificates on multiple Control-M/Agents.

First script: Creating CSRs for certificates that are about to expire

This first script uses API commands to automate the following tasks:

Get a list of Control-M/Servers, using the config servers::get command.
Get a list of Control-M/Agents for each server, using the Config Service command.
Determine which of the Agents has a certificate that is about to reach its expiration date, using the config server:agent:crt:expiration::get command.
Create a Certificate Signing Request (CSR) for each agent that is about to expire, and store all CSR files in one directory. Use the config server:agent:csr::create command.

Signing CSRs

Before running the second script, get the security team at your organization to sign the CSRs that were created by the first script.

Second script: Deploy signed certificates to agents

This second script uses API commands to automate the following tasks:

Get a list of Control-M/Servers, using the config servers::get command.
Get a list of Control-M/Agents for each server, using the Config Service command.
Determine which of the Agents has a certificate that is about to reach its expiration date, using the config server:agent:crt:expiration::get command.
Deploy each of the signed certificates to its proper Agent, using the config server:agent:crt::deploy command.