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::add

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

CLI Syntax

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

The following table describes the config server:sshkey:add::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

  • DSA

bits

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

  • 512

  • 768

  • 1,024

  • 2,048

  • 3,076

Larger values provide greater security.

sshKeyData.json

(Optional) Defines 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.

REST API Syntax

cURL:

Copy 
server=controlm
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/server/$server/sshkey/add"

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

config server:sshkey:update::update

The config server:sshkey:update::update command enables you to update an SSH key on the Control-M/Server.

CLI Syntax

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

The following table describes the config server:sshkey:update::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 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
}

REST API Syntax

cURL:

Copy 
server=controlm
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/server/$server/sshkey/update"

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

config server:sshkey::delete

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

CLI Syntax

Copy 
ctm config server:sshkey::delete <server> <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.

REST API Syntax

cURL:

Copy 
server=controlm
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/server/$server/sshkey/$keyName/$passphrase"

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

config server:sshKeysList::get

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

CLI Syntax

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

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

You can use the optional -s switch to run a search with the query string format field1=criteria1&field2=criteria2&field3=criteria3, which contains the following supported fields:

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

REST API Syntax

cURL:

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

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

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

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.

CLI Syntax

Copy 
ctm config server:sshkey::get <server> <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.

REST API Syntax

cURL:

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

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

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