Certificate Configuration

The following API commands enable you to configure certificates on SSL-configured Agents and manage and rotate Certificate Authorities (CA):

• config server:agent:crt:expiration::get

• config server:agent:csr::create

• config server:agent:crt::deploy

• config ca:server:agent:list::get

• config ca:server:agent::add

• config ca:server:agent::delete

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.

You can use this API command in a script that automates certificate updates, as described in Automating SSL Certificate Updates on Agents.

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

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

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

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.

You can use this API command in a script that automates certificate updates, as described in Automating SSL Certificate Updates on Agents.

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: 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"

-o $file_path$file_name

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.

{  
   "organization": "example_organization",  
   "organizationUnit": "example_unit",  
   "cityLocality": "example_city",  
   "stateProvince": "example_state",  
   "country": "CO",  
   "emailAddress": "[email protected]"
}

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.

You can use this API command in a script that automates certificate updates, as described in Automating SSL Certificate Updates on Agents.

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: 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"

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

Automating SSL Certificate Updates on Agents

As the administrator, you can automate updates to SSL certificates on multiple Agents by incorporating API commands in scripts.

config ca:server:agent:list::get

The config ca:server:agent:list::get command retrieves a list of CAs from the trusted keystore of the Control-M/Agent.

server=controlm
agent=quickstart
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" "$endpoint/config/ca/server/$server/agent/$agent/list"

The following table describes the config ca:server:agent:list::get command parameters.

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

Response

The following example shows the config ca:server:agent:list::get response parameters.

{
  "ca_list": [
    {
      "alias": "ca1",
      "owner": "o=test org intermediate2,cn=test intermediate2 ca2",
      "issuer": "o=test org intermediate1,cn=test intermediate1 ca1",
      "valid_from": "wed sep 24 13:34:52 idt 2025",
      "valid_until": "mon sep 23 13:34:52 idt 2030"
    },
    {
      "alias": "ca2",
      "owner": "o=test org intermediate1,cn=test intermediate1 ca1",
      "issuer": "o=test org root,cn=test root ca",
      "valid_from": "wed sep 24 13:34:52 idt 2025",
      "valid_until": "mon sep 23 13:34:52 idt 2030"
    },
    {
      "alias": "ca3",
      "owner": "o=test org root,cn=test root ca",
      "issuer": "o=test org root,cn=test root ca",
      "valid_from": "wed sep 24 13:34:51 idt 2025",
      "valid_until": "sat sep 22 13:34:51 idt 2035"
    }
  ]
}

The following table describes the config ca:server:agent:list::get command parameters that are shown in the above response.

config ca:server:agent::add

The config ca:server:agent::add command enables you to add a new CA or CA chain to the trusted keystore of the Control-M/Agent based on the provided aliases.

server=controlm
agent=quickstart
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" -X POST "$endpoint/config/ca/server/$server/agent/$agent" \
--form 'caFile=@"/C:/Temp/CA_chain.pem"' \
--form 'aliases=@"/C:/Temp/aliases.json"' 

The following table describes the config ca:server:agent::add command parameters.

{"aliases":
  [
    {"name":"AliasName1"},
    {"name":"AliasName2"},
    {"name":"AliasName3"}
  ]
}

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config ca:server:agent::delete

The config ca:server:agent::delete command deletes a CA from the trusted keystore of the Control-M/Agent based on the provided aliases.

server=controlm
agent=quickstart
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json" -X DELETE "$endpoint/config/ca/server/$server/agent/$agent" \
--form 'aliases=@"/C:/Temp/aliases.json"' 

The following table describes the config ca:server:agent::delete command parameters.

{"aliases":
  [
    {"name":"AliasName1"},
    {"name":"AliasName2"},
    {"name":"AliasName3"}
  ]
}

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.