SSH Key Configuration

The following API commands enable you to configure SSH Keys, which enable secure, key-based authentication by Control-M jobs and integrations.

These commands require Control-M/EM 9.0.21.200 or higher.

config server:sshkey::add

The config server:sshkey::add command enables you to add a new SSH key to a Control-M/Server.

  • CLI

  • REST

ctm config server:sshkey::add <server> <keyName> <passphrase> [format] [type] [bits] [-f sshKeyData.json] [-p]

The following example shows the REST API syntax for the config server:sshkey::add command in cURL.

Copy 
server=IN01

curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST
"%endpoint%/config/server/$server/sshkey/add"

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

Parameter

Description

server

Defines the Control-M/Server name.

keyName

Defines the key name.

Valid Values: 1–256 alphanumeric characters and _ (underscores).

passphrase

Defines the key file password, which is encrypted in Control-M for secure storage and transmission.

format

(Optional) Determines the format that the SSH key is generated in, as follows:

  • OpenSSH

  • SSH2

type

(Optional) Determines the type of SSH key to generate, as follows:

  • RSA

  • ECDSA

bits

(Optional) Determines the number of key size (in bits), as follows:

  • ECDSA:

    • 256

    • 384

    • 521

  • RSA:

    • 3,072

    • 4,096

Larger bit values increase security.

sshKeyData.json

(Optional) Defines the pathname to a JSON file that contains the following parameters, which eliminates the need to include them in the API command:

  • keyname

  • passphrase

  • format

  • type

  • bits

Copy 
{
   "keyName": "keyname",
   "passPhrase": "12365",
   "format": "OpenSSH",
   "type": "RSA",
   "bits": 1024
}

-p

(Optional) Adds a password confirmation prompt.

config server:sshkey::update

The config server:sshkey::update command enables you to update an existing SSH key that is stored on a Control-M/Server.

  • CLI

  • REST

ctm config server:sshkey::update <server> <keyName> <passphrase> [-f sshKeyData.json]

The following example shows the REST API syntax for the config server:sshkey::update command in cURL.

Copy 
server=IN01

curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST
"%endpoint%/config/server/$server/sshkey/update"

The following table describes the config server:sshkey::update command parameters.

Parameter

Description

server

Defines the Control-M/Server name.

keyName

Defines the key name.

Valid Values: 1–256 alphanumeric characters and _ (underscores).

passphrase

Defines the key file password, which is encrypted in Control-M for secure storage and transmission.

sshKeyData.json

(Optional) Defines the pathname to a JSON file that contains the following parameters, which eliminates the need to include them in the API command:

  • keyname

  • passphrase

  • format

  • type

  • bits

Copy 
{
   "keyName": "keyname",
   "passPhrase": "12365",
   "format": "OpenSSH",
   "type": "RSA",
   "bits": 1024
}

config server:sshkey::deleteSshKey

The config server:sshkey::deleteSshKey command enables you to delete an SSH key from a Control-M/Server.

  • CLI

  • REST

ctm config server:sshkey::deleteSshKey <server> <keyName> <passphrase> [-f <configuration file>]

The following example shows the REST API syntax for the config server:sshkey::deleteSshKey command in cURL.

Copy 
server=IN01

curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST
"%endpoint%/config/server/$server/sshkey/deleteSshKey"
-d '{"keyName": "$keyName","passphrase": "$passphrase"}'

The following table describes the config server:sshkey::deleteSshKey command parameters.

Parameter

Description

server

Defines the Control-M/Server name.

keyName

Defines the key name.

Valid Values: 1–256 alphanumeric characters and _ (underscores).

passphrase

Defines the key file password, which is encrypted in Control-M for secure storage and transmission.

configuration file

(Optional) Defines the pathname to a JSON file that contains the required keyName and passphrase, which eliminates the need to include them in the API command.

config server:sshkey::delete

The config server:sshkey::delete command enables you to delete an SSH key from a Control-M/Server.

This API command is planned to be deprecated soon. Use config server:sshkey::deleteSshKey instead.

  • CLI

  • REST

ctm config server:sshkey::delete <server> <keyName> <passphrase>

The following example shows the REST API syntax for the config server:sshkey::delete command in cURL.

Copy 
server=IN01

curl -H "x-api-key: $token" -H "Content-Type: application/json" -X DELETE
"%endpoint%/config/server/$server/sshkey/$keyName/$passphrase"

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

Parameter

Description

server

Defines the Control-M/Server name.

keyName

Defines the key name.

Valid Values: 1–256 alphanumeric characters and _ (underscores).

passphrase

Defines the key file password, which is encrypted in Control-M for secure storage and transmission.

config server:sshKeysList::get

The config server:sshKeysList::get command enables you to get the following details about all the SSH keys that are stored on a Control-M/Server:

  • Key name

  • Number of bits

  • Format

  • Key type

  • Minimum Agent version

  • CLI

  • REST

ctm config server:sshKeysList::get <server> [-s "<search query>"]

Where:

  • <server>: Defines the Control-M/Server name.

  • (Optional) "<search query>": Searches the query string in the following format:

    -s "field1=criteria1&field2=criteria2&field3=criteria3"

The following example shows the REST API syntax for the config server:sshKeysList::get command in cURL.

Copy 
server=IN01

curl -H "x-api-key: $token" -H "Content-Type: application/json" -X GET
"%endpoint%/config/server/$server/sshKeysList?keyName=b*&format=SSH2"

(Optional) You can type the ? switch to search the query string in the following format:

field1=criteria1&field2=criteria2&field3=criteria3

The following table describes the available config server:shKeysList::get command fields.

Field

Description

keyName

Defines the key name.

Valid Values: 1–256 alphanumeric characters and _ (underscores).

The * and ? wildcards are supported.

format

Determines the format of the SSH key, as follows:

  • OpenSSH

  • SSH2

type

Determines the type of SSH key, as follows:

  • RSA

  • DSA

config server:sshkey:getSshKey::get

The config server:sshkey:getSshKey::get command enables you to get an SSH key that is stored on a Control-M/Server.

  • CLI

  • REST

ctm config server:sshkey:getSshKey::get <server> <keyName> <passphrase>

The following example shows the REST API syntax for the config server:sshkey:getSshKey::get command in cURL.

Copy 
server=IN01

curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST
"%endpoint%/config/server/$server/sshkey/getSshKey"
-d '{"keyName": "$keyName","passphrase": "$passphrase"}'

The following table describes the config server:sshkey:getSshKey::get command parameters.

Parameter

Description

server

Defines the Control-M/Server name.

keyName

Defines the key name.

Valid Values: 1–256 alphanumeric characters and _ (underscores).

passphrase

Defines the key file password, which is encrypted in Control-M for secure storage and transmission.

config server:sshkey::get

The config server:sshkey::get command enables you to get an SSH key that is stored on a Control-M/Server.

This API command is planned to be deprecated soon. Use config server:sshkey:getSshKey::get instead.

  • CLI

  • REST

ctm config server:sshkey::get <server> <keyName> <passphrase>

The following example shows the REST API syntax for the config server:sshkey::get command in cURL.

Copy 
server=IN01

curl -H "x-api-key: $token" -H "Content-Type: application/json" -X GET
"%endpoint%/config/server/$server/sshkey/$keyName/$passphrase"

The following table describes the config server:sshkey::get command parameters.

Parameter

Description

server

Defines the Control-M/Server name.

keyName

Defines the key name.

Valid Values: 1–256 alphanumeric characters and _ (underscores).

passphrase

Defines the key file password, which is encrypted in Control-M for secure storage and transmission.