SSH Key Configuration

The following API commands enable you to configure SSH Keys:

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 an SSH key to the 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 with RunAsUserEncryptionHelper.

format

(Optional) Determines which format to generate the SSH key in, as follows:

  • OpenSSH

  • SSH2

type

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

  • RSA

  • ECDSA

bits

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

  • ECDSA:

    • 256

    • 384

    • 521

  • RSA:

    • 3,072

    • 4,096

Larger values provide greater 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 CLI:

  • keyname

  • passphrase

  • format

  • type

  • bits

This eliminates the need to include

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 SSH key on the 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 with RunAsUserEncryptionHelper.

sshKeyData.json

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

  • 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 the 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 with RunAsUserEncryptionHelper.

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 the 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 with RunAsUserEncryptionHelper.

config server:sshKeysList::get

The config server:sshKeysList::get command enables you to get the SSH key data from all objects.

  • CLI

  • REST

You can use the optional -s switch to run a search with the query string format "field1=criteria1&field2=criteria2&field3=criteria3".

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

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

You can use the optional ? switch to run a search with the query string format field1=criteria1&field2=criteria2&field3=criteria3.

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"

Where <server> defines the Control-M/Server name.

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

Field

Description

keyName

Defines the key name.

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

Supported wildcards are * and ?.

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 save a public key on your Agent and transfer it to an Agentless Host.

  • 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 with RunAsUserEncryptionHelper.

config server:sshkey::get

The config server:sshkey::get command enables you to save a public key on your Agent and transfer it to an Agentless Host.

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 with RunAsUserEncryptionHelper.