ctmsskf Command

Purpose

Displays and manages the contents of a message security services (MSS) key file.

Syntax

ctmsskf {-a │ -d │ -l │ -h} [-f key_file] [-t key_type] [-v key_version] [-k key_value]

Description

The ctmsskf command displays and manages the contents of a message security services (MSS) typed key file. Use this command to add a key to, delete a key from, or list the contents of a key file.

Adding a key:

When you use this command to add a key entry to a key file, you must specify the following:

the name of the key file where the key is to be added
the type of the key to add
optionally, the version of the key that is to be added to the key file
the 16-digit value of the key

If the specified key file does not exist, it is created. If the specified key file does exist, the ctmsskf command verifies that the key type specified for the new key matches the type used by the keys already recorded within the file. Only keys of the same type can be added to an existing key file. When a key is successfully added to the file, that version of the key becomes the active key version. If a key version is specified using the -v key_version flag, key_version is used as the new version number and is made the active version. If key_version is not specified, the key is added using a key version value that is one greater than the previous active key version number.

Existing versions of a key cannot be replaced. To replace an existing version of a key or to change the value of an existing version of a key, that key version must first be deleted using the -d flag, and then added again using the -a flag. The command returns an error if you try to add a key that uses a version number already in use by a key within an existing key file. In general, key replacements should only be performed on the value of the key that is currently active, as replacing the value of an older key version makes the older key version active.

Because key versions can be added to the key file in any order, the highest key version number may or may not be the key version that is currently active. Use the -l flag to determine which key version is currently active for a file.

Deleting a key:

When you use this command to delete a key entry from a key file, you must specify the following:

the name of the key file from where the key is to be deleted
optionally, the type of key to delete
optionally, the version of the key to delete

If the key specified is empty, does not exist, or does not have a proper header, the command returns an error. If the key type is specified and it does not match the key type in the header of the, the command returns an error. If the key version is specified, the command locates the record corresponding to the version provided and purges it from the file. If there is no such record, the command returns an error. If no key version is provided, the command purges only the records that are marked as inactive.

Listing the contents of a key file:

When you use this command to list the contents of a key file, the following information is displayed:

the header of the key file.
the list of keys in the key file.
The following information is displayed for each key:
- an indication of whether the record is inactive
- the version of the key
- the type of the key
- the 16-digit value of the key

Flags

-a: Adds a key to the key file. The -f, -k, and -t flags must also be specified.
-d: Deletes a key from the key file. The -f and -v flags must also be specified. If the -t flag is specified, the command checks to see if the type of the key file is the same as the key type provided.
-l: Lists the contents of the key file. The -f flag must also be specified. If the -v flag is specified, the command lists only the key that matches the version number provided.
-f key_file: Specifies the name of the key file. The key file must be a valid key file created by MSS API or by this command.
-t key_type: Specifies the type of the key to add. If the specified key file is not empty, the command checks to see if the key type specified matches the key type in the header of the key file. The valid key type values are: 3des_md5, aes256_md5, des_cbc, des_md5, rsa512_sha, and rsa1024_sha.
-v key_version: Specifies the version of the key.
-k key_value: Specifies the 16-digit value of the key.
-h: Writes the command's usage statement to standard output.

Security

The file system permission of the key files is determined by the application owning the file. If the invoker doesn't have sufficient authority to open the file, the command fails.

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.
9: If the -a flag was specified, the command detected a key within the key file that used the same version number as the one specified by the -v flag. If the -d flag was specified, the command was unable to locate a key in the key file using the version number specified by the -v flag. The key file was not modified.
21: The key file could not be located. Verify that the path name for the key file specified by the -f flag is correct.
27: The key type specified by the -t flag does not match the type for keys stored in the file specified by the -f flag. The requested action was not performed.
30: ctmsskf was unable to obtain exclusive use of the key file. Another instance of this command may be running and attempting to modify the same file, or the process that makes use of this key file may be examining the file. Retry the command at a later time.
36: The command user does not have sufficient permission to modify the contents of the key file.
37: The key file appears to be corrupted. Try to list the contents of the file using the -l flag to verify if the file is corrupted. Follow the problem resolution advice listed in the error message for further recovery action.

Restrictions

This command works only on MSS-formatted key files.

Standard Output

When the -h flag is specified, this command's usage statement is written to standard output. When the -i flag is specified, the list of available key generation methods is displayed. When the -l flag is specified, one or more keys from the key file are displayed.

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/ctmsskf: Contains the ctmsskf 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