Commands Reference, Volume 1

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 ] | -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 UNIX-identity-based authentication. 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 UNIX-identity-based 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 UNIX-identity-based authentications on this node. This flag is not valid with the -h or the -i flag.
-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.
-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 option. 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.
-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: ctsidmck successfully found a mapped identity for network_ID.
3: The command detected a failure in the operation of the cluster security library mechanism pluggable module (MPM) corresponding to the security mechanism what was requested. The command was unable to search for a possible mapped identity for network_ID in this case. This failure may be accompanied by descriptive output indicating the nature of the MPM failure. Consult this output and perform any recommended actions.
4: The caller invoked the command incorrectly, omitting required options and arguments, or using mutually exclusive options. The command terminated without attempting to find a mapped identity for network_ID.
6: A memory allocation request failed during the operation of the command. The command was unable to search for a possible mapped identity for network_ID in this case.
21: The command was unable to locate any of the identity mapping definition files on the local system. The command was unable to search for a possible mapped identity for network_ID in this case. Verify that at least one identity mapping definition file exists on the system.
22: The command was unable to dynamically load the cluster security library mechanism pluggable module (MPM) corresponding to the security mechanism what was requested. The module may be missing, corrupted, or one of the shared libraries used by this module may be missing or corrupted. The command was unable to search for a possible mapped identity for network_ID in this case. This failure may be accompanied by descriptive output indicating the nature of the MPM failure. Consult this output and perform any recommended actions.
37: At least one of the identity mapping definition files on the system appears to be corrupted. The command was unable to search for a possible mapped identity for network_ID in this case. Verify that none of the identity mapping files are corrupted, truncated, or contain syntax errors.
38: ctsidmck could not locate a mapped identity for network_ID. No entry within any of the identity mapping definition files yielded a mapped identity for the specified security network identifier.

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

ctsidmck writes any mapped identity found for the security network identifier to standard output. If a medium or high level of detail is requested, any definitions displayed by this command are also written to standard output.

When the -h flag is specified, this command's usage statement is written to standard output.

Standard Error

Descriptive information for any detected failure condition is written to the 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

/usr/sbin/rsct/bin/ctskeygen: Contains the ctskeygen command

Files

/usr/sbin/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.

Related Information

Commands: ctsthl

Daemons: ctcasd

Files: ct_has.pkf, ct_has.qkf, ct_has.thl