ptk7tokmigration

Utility to migrate tokens from ProtectServer 2 HSMs to ProtectServer 3 HSMs.

Syntax

The following ptk7tokmigration syntax can can be used.

Commands

The following ptk7tokmigration commands are available.

check

Check HSM Identity keys for consistency on the devices specified by the <targets> parameter and report anomalies. check ensures that the peer keys match the device private key they represent and that all key objects have been created with appropriate security attributes.

Note

check will fail if any of the devices specified by the <targets> parameter are offline.

gen

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, ptk7tokmigration requires the Administration Security Officer (ASO) PIN. The -o<so-pin> parameter can be used to supply a default ASO 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.

getid

Store the public keys of online HSMs specified by the <targets> parameter in a file that is specified by the -p<pubkey> option.

list

List summary information for HSM Identity keys located on the devices specified by the <targets> parameter.

The -t<types> 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 or cert.

remove

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 ptk7tokmigration remove a devices own HSM Identity key-pair.

To complete this command, ptk7tokmigration requires the ASO PIN. The -o<so-pin> 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

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 the peer devices to be trusted are offline, this command is used with the -p<pubkey> option to specify and use the public key file of the offline peer devices.

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, ptk7tokmigration requires the ASO PIN. The -o<so-pin> 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.

it

Import a token image into the specified token. The -s<slot> parameter identifies the token that will be replaced with the imported token image (by default, slot 0 is used). The <filename> parameter specifies the token image file to import.

To complete this operation, ptk7tokmigration will prompt for the User PIN of the destination token.

When importing into an un-initialized token, ptk7tokmigration will prompt for the SO PIN of the destination token. If the device is running in FIPS mode, ptk7tokmigration will prompt for the device administrator PIN of the destination token.

Options

The options shown below are available for ptk7tokmigration.

<filename>

The name of the token image file that is output after exporting a ProtectServer 2 HSM token.

<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.

Note

When this argument is specified with the trust command, devices cannot be specified using positional numbers.

-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, ptk7tokmigration will report an error.

-f, --force

Force the command.

-o<so-pin>, --so-pin=<so-pin>

Specifies the Administration Security Officer (ASO) PIN. Use of this operation is a security risk due to the tools command line being visible in the systems process list.

-p<pubkey>, --pubkey=<pubkey>

Public key file.

-s<slot>, --slot-num=<slot>

Specifies the slot to operate on. Default value is 0 (zero), however must be specified when using the it command.

-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>, --user-pin=<pin>

Specifies the User PIN. Use of this operation is a security risk due to the tools command line being visible in the systems process list.

-z<keysize>, --keysize=<keysize>

Size of keys to generate.