ctskeygen Command

Purpose

Generates cluster security services private and public keys for the local system and stores these keys in locally-mounted files.

Syntax

ctskeygen -n [-f] [ -m method ] [ -p public-file ] [ -q private-file ] │ -d │ -i │ -h

Description

The ctskeygen command generates host identifier keys — a private key and public key pair — to be used by the cluster security services library (libct_sec) in RSCT host-based authentication (HBA). The command creates a new private key for the node, derives a public key from the new private key, and stores these keys to files on the local node.

Whenever the node's private and public keys are modified, the node's new public key must be distributed to all nodes within the cluster and placed in the trusted host list files on these nodes, replacing the previous value stored there for this node. If this is not done, the node that has generated new private and public keys will be unable to authenticate with other nodes in the cluster using HBA authentication.

Flags

-n: Generates host identifier keys (private and public keys).
-f: Forces ctskeygen to record the keys it generates to the private and public key files if these files already exist. By default, the command will not overwrite these files if they exist, because the presence of the files indicates that the cluster security services service may be active. Removing or modifying these files without informing other nodes of the change in the public key value will cause failures in HBA authentications on this node. This flag is not valid with the -h or the -i flag.
-m method: Instructs the command to use the specified key generation method in creating the host identifier keys. Valid parameters for this flag can be displayed using the -i flag. This flag is not valid with the -h and -i flags.
-p public-file: Specified the fully-qualified path name of the file to be used to store the local host's public key. If this file exists, the command will not overwrite the contents of this file unless the -f flag is also specified. If the -p flag is not specified, the command records this key to the /var/ct/cfg/ct_has.pkf file. This flag is not valid with the -h and -i flags.
-q private-file: Specified the fully qualified path name of the file to be used to store the private key of the local host. If this file exists, the command will not overwrite the contents of this file unless the -f flag is also specified. If the -q option is not specified, the command records this key to the file /var/ct/cfg/ct_has.qkf. This flag is not valid with the -h and -i flags.
-d: Displays the current public key value for the local system.
-i: Displays information about the key generation methods supported by this version of the command. ctskeygen displays messages to indicate which values are currently supported as arguments to the -m flag, and what the command will use as a default setting for the -m flag.
-h: Writes the command's usage statement to standard output.

Parameters

network_ID: Specifies the security network identifier to be mapped. This should be an identity that can be assumed by a client application of a trusted service.

Security

Permissions on the ctskeygen command permit only root to run the command.

Exit Status

0: The command completed successfully.
4: The caller invoked this command incorrectly, omitting required flags and parameters, or using mutually-exclusive flags. This command terminated without processing the request.
6: A memory allocation request failed during the operation of this command. The command was unable to complete the requested action.
12: The command user does not have sufficient permission to view or modify the contents of the key file.
21: The key file could not be located or could not be created.
30: ctskeygen was unable to obtain exclusive use of the public or private key file. Another instance of this command may be running and attempting to modify the keys, or the ctcasd daemon may be examining these files. Retry the command at a later time.
37: The public or private key file appears to be corrupted. Try to view the public key value using the -d flag to verify if the file is corrupted. Follow the problem resolution advice listed in the error message for further recovery action.

Restrictions

Cluster security services supports its own file formats, private key formats, and public key formats only.
Trusted host lists are modifiable using the ctsthl command only.
Cluster security services does not provide an automated utility for creating, managing, and maintaining trusted host lists throughout the cluster. This is a procedure left to either the system administrator or the cluster management software.

Standard Output

When the -h flag is specified, this command's usage statement is written to standard output. When the -d flag is specified, the public key value stored in the public key file is written to standard output.

Standard Error

Descriptive information for any detected failure condition is written to standard error.

Examples

To obtain the list of supported key generation methods:
```
ctskeygen -i
```
To create new host identifier keys for the local system using the default settings:
```
ctskeygen -n
```
To create new host identifier keys for the local system using 512-bit RSA private keys, storing these keys in locations other than the default location:
```
ctskeygen -n -m rsa512 -p /mysec/public -q /mysec/private
```

Location

/opt/rsct/bin/ctskeygen: Contains the ctskeygen command

Files

/opt/rsct/cfg/ctsec_map.global: The default identity mapping definition file. This file contains definitions required by the RSCT cluster trusted services in order for these systems to execute properly immediately after software installation. This file is ignored if the cluster-wide identity mapping definition file /var/ct/cfg/ctsec_map.global exists on the system. Therefore, any definitions within this file should also be included in the cluster-wide identity mapping definition file, if that file exists.
/var/ct/cfg/ctsec_map.local: Local override to the cluster-wide identity mapping definitions. Definitions within this file are not expected to be shared between nodes within the cluster.
/var/ct/cfg/ctsec_map.global: Cluster-wide identity mapping definitions. This file is expected to contain identity mapping definitions that are common throughout the cluster. If this file exists on the system, the default identity mapping definition file is ignored. Therefore, if this file exists, it should also contain any entries that would also be found in the default identity mapping definition file.