ctmkeygen

The ctmkeygen utility generates SSH private and public key pairs.

When creating or modifying the job owner definition, you can choose to use either public or private key authentication instead of password authentication.

The ctmkeygen utility manages the key table that contains the logical key name as the unique table key, the private key, and the key passphrase (encrypted). The generated public key (unencrypted) is stored in a file.

Running the ctmkeygen Utility

This procedure describes how to run the ctmkeygen utility, which generate SSH private and public key pairs. The ctmkeygen utility can be run either in interactive mode or batch invocation.

Begin

  1. Do one of the following:

    • UNIX: Log in to a Control-M/Server account

    • Windows: Open a command prompt window where Control-M/Server is installed.

  2. Type one of the following commands:

    • For interactive mode:

      ctmkeygen

      The Control-M Key Generator Utility menu is displayed. The options in this menu and in all other menus provided by this utility can be selected by typing the option number or command letter and pressing <Enter>.

    • For batch mode:

      Specify one of the following commands:

      • ctmkeygen -action add -name <logicalKeyName> -passphrase <keyPassphrase> -type rsa|dsa -bits 512|768|1024|2048|3072 -format openssh|ssh2 -path <publicKeyPath>

      • ctmkeygen -action update -name <logicalKeyName> -passphrase <keyPassphrase> [-type rsa|dsa] [-bits 512|768|1024|2048|3072] [-format openssh|ssh2] -path <publicKeyPath>

      • ctmkeygen -action delete -name <logicalKeyName> -passphrase <keyPassphrase>

      • ctmkeygen -action list

      • ctmkeygen -action export -filename <exportFileName>

      • ctmkeygen -action import -filename <importFileName> -data append|truncate

      • ctmkeygen help

ctmkeygen Utility Parameters

The following table describes the parameters in the ctmkeygen utility:

Parameter

Description

-name

Defines a logical name of the key that is used as a unique identifier. It also determines the name of the public key file. The name is comprised of letters, numbers, and underscores.

-passphrase

Defines a phrase used as a key to encrypt the key itself.

-type

Specifies the standard used for the key. Mandatory when used with add, optional when used with update.

Valid values:

  • RSA

  • DSA

-bits

Specifies the strength of the encryption key in bits. Mandatory when used with add, optional when used with update.

Valid values:

  • 512

  • 768

  • 1024

  • 2048

  • 3072

    The minimum value of the bits must be at least equal to the minimum value of bits specified for the SSH server.

-format

Specifies the public key file format. It must match the format used by the SSH server. Mandatory when used with add, optional when used with update.

Valid values:

  • openssh – for OpenSSH servers

  • ssh2 – for ssh2 servers

-path

Specifies the location where the public key file is created.

-filename

Specifies the public key name. The format of the file depends on what is specified for the –format parameter, described above.

-data

Describes what action to take with the imported data from the text file.

Specify one of the following:

  • append: the details of the SSH keys from the imported text file are added to the existing SSH keys

  • truncate: the details of the SSH keys from the imported text file replace the existing SSH keys

ctmkeygen Utility Actions

The following table describes the actions in the ctmkeygen utility:

Action

Description

add

Creates a new entry in the key table. It also verifies that a key with the same name does not exist. All the parameters are mandatory.

update

Modifies the details of an existing entry in the key table. The entry includes the same fields as used to create a new key pair. The updated entry replaces the existing entry in the key table in the database and the public key file. The passphrase must match the one that was used to create the existing key.

For the optional parameters, if a value not specified, the value stored in the Control-M/Server database is used.

delete

Deletes the entry associated with the logical key name. The passphrase must match the one that was used to create the existing key.

list

Returns a list of lines, each containing: the logical key name, type, bits, and format.

export

Exports the details of the keys stored in the key table to a text file.

ctmkeygen -action export -filename $HOME/ctm_server/data/key_details.txt

import

Imports the details of the keys stored in the key table.

Using the import parameter enables you to:

  • prepare and save files of keys that can be reused

  • specify utility input longer than the number of characters allowed in the command line

    ctmkeygen -action import -filename $HOME/ctm_server/data/key_details.txt

help

Displays the usage of the ctmkeygen utility.

Copying Public Keys to the SSH Server

This procedure describes how to copy public keys to the SSH server. The public key must be copied to the SSH server. If such a file already exists on the SSH server, you must choose to either append or truncate the new file to the existing one.

Begin

  • Copy the public key to the SSH server according to the SSH server requirements:

    • For OpenSSH on UNIX, the public keys file is:

      <jobOwnerHomeDirectory>/.ssh/authorized_keys

    • For SSH Tectia on UNIX, the public keys file is:

      <jobOwnerHomeDirectory>/.ssh2/authorization

    • For SSH Tectia on WINDOWS, the public keys file is:

      <jobOwnerHomeDirectory>\.ssh2\authorization

Copy Public Keys to SSH Server Example

Create an entry in the key table with the following specifications:

Parameter

Value

key name

key1

passphrase

myphrase

type

dsa

bits

512

format

ssh2

path

/home/ctm900

  • Specify the following command:

    ctmkeygen -action add -name key1 -passphrase myphrase -type dsa -bits 512 -format ssh2 -path /home/ctm900

    The following message is displayed:

    Copy 
    Creating SSH key. Please wait...
    SSH key created successfully.

  • Assume that modifications are required to the key created in Example 1. To change the type to rsa, the number of bits to 1024 and the format to openssh, specify the following command:

    ctmkeygen -action update -name key1 -passphrase myphrase -type rsa -bits 1024 -format openssh -path /home/ctm900

    The following message is displayed:

    Copy 
    Updating SSH key. Please wait...
    SSH key update ended successfully.

  • To delete the key entry created in Example 1, specify the following command:

    ctmkeygen -action delete -name key1 -passphrase myphrase

    The following message is displayed:

    Entry deleted successfully.

  • To display a list of SSH keys in the key table, specify the following command:

    ctmkeygen -action list

    The following is displayed:

    Copy 
    Name                           Type       Bits       Format
    ----                           ----       ----       ------
    first                          RSA        512        OPENSSH
    mykey                          RSA        1024       OPENSSH
    2 keys were found.

  • To create an export text file containing the details of the SSH keys, specify the following command:

    ctmkeygen -action export -filename /home/ctm900/my.exp

    The following is displayed:

    Copy 
    Exporting data, please wait...
    Export ended successfully.
    Check report file ~<controlm_owner>/ctm_server/proclog/export_report_5020.txt’ for details.

  • To import the my.exp text file, which contains the details of the SSH keys that replaces the current information, specify the following command:

    ctmkeygen -action import -filename /home/ctm900oe/my.exp -data truncate

    The following message is displayed:

    Copy 
    Importing data, please wait...
    Import ended successfully.
    Check report file ~<controlm_owner>/ctm_server/proclog/import_report_535a.txt’ for details.