CTIDENT

Utility for establishing and maintaining trust between devices within the SafeNet 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.

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> to <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 key types are listed.

The –a parameter lists all of the non-sensitive attributes for each key.

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

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.