ctident
Utility for establishing and maintaining trust between devices within the ProtectToolkit-C environment.
The ctident utility establishes trust between devices. This includes operations performed by the Administrative Token SO to establish trust, as well as operations performed by any user to verify trust relationships.
A device trusts another peer when the device holds the peer's HSM Identity public-key in its Administrative Token.
NOTE When operating in WLD/HA mode, this utility should only be used to view the configuration. Any changes to the configuration should be made in NORMAL mode. See Operation in WLD Mode and Operation in HA Mode for more information about these operating modes.
Syntax
Generate new HSM ID key pair
ctident gen [-b] [-f] [-o<so_pin>] <targets>
Add trust for <peers> to <targets>
ctident trust [-b] [-f] [-o<so_pin>] <targets> <peers>
Remove trust for <peers> from <targets>
ctident remove [-b] [-o<so_pin>] <targets> <peers>
List HSM ID keys
ctident list [-b] [-t<types>] [-a] <targets>
Check HSM ID keys
ctident check [-b] <targets>
Commands
When specifying the command, the user need only supply the minimum number of characters to uniquely distinguish the command.
| Command |
Description |
|---|---|
| check |
The check key command check is used to check HSM Identity keys for consistency on the devices specified by the <targets> parameter. Any anomalies will be reported. This command ensures that the peer keys match the device private key they represent, and ensures that all key objects have been created with appropriate security attributes. |
| gen |
The generate key command gen is used to generate the HSM Identity key-pair on the devices specified by the <targets> parameter. If a device already has an identity key a key will not be generated and a warning will be issued, unless the -f parameter is used to force key regeneration. When a key is regenerated, the existing key is destroyed BEFORE the new key has been generated to avoid any inconsistencies that could occur with multiple keys. To complete this command, ctident requires the SO PIN of the administrative token. The -o parameter can be used to supply a default SO PIN. Since multiple devices can be targeted with this command, differing PINs may be required for each device. When a default PIN is not provided or if the current PIN is incorrect, the PIN will be prompted for. The batch mode -b parameter can be used to disable PIN prompting. |
| list |
The list key command list is used to list summary information for HSM Identity keys located on the devices specified by the <targets> parameter. The -t parameter restricts the types of keys listed. By default all HSM Identity keys are listed. The -a parameter lists all of the non-sensitive attributes for each key/cert. |
| remove |
The remove key command remove is used to remove HSM Identity keys from the devices specified by the <targets> parameter. The <peers> parameter specifies the peer device keys to remove. If the serial number format is used to identify peers, the peer device need not be available for the command to succeed since peer keys are identified by device serial number. If the <peers> parameter specifies the value local, the devices own local HSM Identity key-pair is removed. This is the only way to have ctident remove a devices own HSM Identity key-pair. To complete this command, ctident requires the SO PIN of the administrative token. The -o parameter can be used to supply a default SO PIN. Since multiple devices can be targeted with this command, differing PINs may be required for each device. When a default PIN is not provided or if the current PIN is incorrect, the PIN will be prompted for. The batch mode -b parameter can be used to disable PIN prompting. |
| trust |
The trust key command 'trust' is used to add peer HSM Identity public-keys to the devices specified by the <targets> parameter. The <peers> parameter specifies one or more peer devices to trust. If a device already has a trusted identity key for a peer, the new key will not be trusted and a warning will be issued, unless the -f parameter is used to force the trust. When forcing trust, the existing peer key is destroyed BEFORE the new key is created to avoid any inconsistencies that could occur with multiple keys. Before trusting a key a number of checks are performed; the public key is checked to ensure it matches the device private key, and both the public and private key objects are checked to ensure they have been created with appropriate security attributes. To complete this command, ctident requires the SO PIN of the administrative token. The -o parameter can be used to supply a default SO PIN. Since multiple devices can be targeted with this command, differing PINs may be required for each device. When a default PIN is not provided or if the current PIN is incorrect, the PIN will be prompted for. The batch mode -b parameter can be used to disable PIN prompting. |
Options
|
Option |
Description |
|---|---|
|
<targets> |
Specifies a comma-separated list of device numbers. The modifier, sn:<serial> allows device serial numbers to be specified as opposed to device positional numbers. The special value all denotes all devices. |
|
<peers> |
Specifies a comma-separated list of peer device numbers. The modifier, sn:<serial> allows device serial numbers to be specified as opposed to device positional numbers. The special value all denotes all devices other than the specific target device on which the command is currently being performed on. The special value local affects the devices own local HSM Identity key-pair and only has effect with the remove command. |
| -a |
--attributes Output all non-sensitive attributes of a key. |
| -b |
--batch Batch mode. Do not prompt for anything, including PINs. If the required information was not supplied on the command line ctident will report an error. |
| -f |
--force Force the command, even if the key already exists. |
|
-o<pin> |
--so-pin=<pin> Specifies the security officer (SO) PIN. Use of this operation is a security risk due to the tools command line being visible in the systems process list. |
|
-t<types> |
--type=<types> Specifies a comma-separated list of key types. The available key types are: pri - local private keys pub - local public keys peer - peer public keys all - all key types |
| -u<pin> | Specifies the Administrator PIN. Use of this operation is a security risk due to the tools command line being visible in the systems process list. |
Exit Status
The ctident utility will return a zero(0) exit status when successful. A non-zero exit status is returned on an error. Warnings are not treated as errors.
