ctscachgen Command

Purpose

Creates or replaces an on-disk version of a key cache.

Syntax

ctscachgen -c file-name [-f] [ -i │ -n enc-key-name │ -k enc-key-value -t key-type │ -q ] [-m key-gen-method] [-s cache-size] [-h]

Description

The ctscachgen command generates a key cache and stores the completed cache to an on-disk file named in file-name. This file can later be used and updated by applications through the libct_skc library interfaces.

Flags allow you to specify the type of key to be generated, using the mnemonics that are used for symmetric key types by the ctmsskf command. You can also specify a key value to be used to encrypt the keys available in this cache. The keys are not encrypted by default. In addition, you can specify the number of keys to be stored in the file.

If the file specified in file-name exists, it is overwritten, even if the current contents do not match the flags specified on the command line.

Flags

-c file-name: Specifies the name of the key cache file. It can be either the full path or the relative path to the current directory.
-f: Instructs the command to overwrite an existing key cache file with the same name without asking the invoker to confirm its overwriting.
-i: Displays information about the key cache file specified with the -c flag. The information displayed contains the version of the cache file, the read count, the number of keys in the cache, the type of keys in the cache, and whether they are encrypted with a pre-encryption key. This flag cannot be used in conjunction with the -n, -k, -t, or -q flag.
-n enc-key-name: Provides the name of the file that contains the encryption typed key. This flag cannot be used in conjunction with the -i, -k, -t, or -q flag.
-k enc-key-value: Specifies the key value, expressed in hexadecimal form (6fe45d20a, for example), to be used as the pre-encryption key. By default, no pre-encryption key value is used. This flag must be used with the -t flag. It cannot be used in conjunction with the -i, -n, or -q flag.
-t key-type: Provides the type of the encryption key specified by the -k option. The valid key types are: 3des_md5, aes256_md5, des_cbc, des_md5, rsa512_sha, and rsa1024_sha. This flag must be used with the -k flag. It cannot be used in conjunction with the -i, -n, or -q flag.
-q: Instructs the command to use the host's HBA private key as encryption key used for pre-encrypting the session keys in the on-disk key cache file. This flag cannot be used in conjunction with the -i, -k, -t, or -n flag.
-m key-gen-method: Provides the session key generation method. Valid values are: 3des_md5, aes256_md5, and des_md5. If you do not specify this flag, the default method for generating the session keys is des_md5.
-s cache-size: Provides the size of the on-disk key cache file in terms of number of keys in the cache. If you do not specify this flag, the default cache size is 128 keys.
-h: Writes the command's usage statement to standard output.

Security

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

Exit Status

Upon successful completion, the command returns an exit status code of 0 and generates an on-disk key cache file. In the event of a failure, the routine returns the error code and may remove the existing key cache file that the invoker wants to overwrite.

0: The command completed successfully.
4: Flags are mismatched or not valid. file-name remains unmodified.
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 cannot remove the existing key cache file (file-name remains unmodified) or access or write to the directory where file-name resides.
21: There is not enough space to store file-name or the file-name contents appear corrupt.
27: The key stored in the file specified by the -c flag is not valid or is corrupted. file-name remains unmodified.
36: The invoker cannot access the file specified by the -c flag. file-name remains unmodified.

Restrictions

On-disk key caches are intended to be used solely upon the system on which they were generated. They are not intended to be shared between systems or migrated to another system. If multiple systems access the same key cache file, the protections offered by these keys is lost, because multiple systems and applications have access to information that is supposed to remain secret to a specific application. Therefore, any files created by this command should not be stored in shared file systems or networked file systems.
Files generated by this command are generated in a host-ordered binary format. This format makes it impossible for a key cache file generated on one architecture (such as a Power® platform) to be used on a different architecture (such as an Intel platform).

Standard Output

When the -h flag is specified, this command's usage statement is written to standard output. When the -i flag is specified, information about the key cache file is written to standard output.

Standard Error

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

Examples

To view the keys contained in the key file /my_key_file, enter:
```
ctmsskf -l -f /my_key_file
```
To view the key with version 9 from the key file /my_key_file, enter:
```
ctmsskf -l -v 9 -f /my_key_file
```

To add a key to the key file /my_key_file, enter:

ctmsskf -a -t des_cbc -f /my_key_file -k 16_digit_value

To delete a key from the key file /my_key_file, enter:
```
ctmsskf -d -f /my_key_file -v 10
```
To delete all inactive keys in the key file /my_key_file, enter:
```
ctmsskf -d -f /my_key_file
```

Location

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

Files

/opt/rsct/cfg/ctcasd.cfg: Default configuration for the ctcasd daemon
/var/ct/cfg/ctcasd.cfg: Configuration for the ctcasd daemon, which can be modified by the system administrator
/var/ct/cfg/ct_has.pkf: Default location of the cluster security services public key file for the node
/var/ct/cfg/ct_has.qkf: Default location of the cluster security services private key file for the node
/var/ct/cfg/ct_has.thl: Default location of the cluster security services trusted host list for the node