rocs

rocs -m|--module=<MODULE> [-t|--target=<CARDSET-SPEC>] [-k|--keys=<KEYS-SPEC>] [-c|--cardset=<CARDSET-SPEC>] [-i|--interactive]

  • Restores an OCS from a quorum of its cards

  • Restores softcards

Keys protected by an OCS can only be recovered to another OCS, and not to a softcard. Likewise, softcard-protected keys can only be recovered to another softcard, and not to an OCS.

If you run rocs without any parameters, it enters interactive mode, where it displays a rocs prompt. In interactive mode, it reads and executes commands from stdin:

rocs in interactive mode
'rocs' key recovery tool
Useful commands: 'help', 'help intro', 'quit'.
rocs >

For more information, see:

Solo XC

nShield 5s

Connect + 

Connect XC

nShield 5c

Edge

Remote Admin

n

y

n

n

n

n

n
Option Description

-c, --cardset=CARDSET-SPEC

Specifies all keys protected by a cardset. You can use this option multiple times to specify multiple cardsets.

The value of CARDSET-SPEC can have any of the following forms:

  • [number] cardset-number: A value of this form selects the OCS or softcard with the given number from the list produced by the list cardsets command.

  • [name] cardset-name: A value of this form selects card sets or softcards by their names (the card set or softcard name may be a wildcard pattern in order to select all matching OCSs or softcards).

  • hash cardset-hash: A value of this form selects the OCS or softcard with the given hash.

-i, --interactive

Reads commands interactively, even though keys are specified on the command-line.

-k, --keys=KEY-SPEC

Specifies the keys to recover (to create new passphrase for).

The value of KEYS-SPEC can have one of the following forms:

* mark key-number: A value of this form selects the key with the given number from the list produced by the list keys command. + Examples of usage are: [source] ---- rocs -t <target_OCS> -k <key_number> ---- + [source] ---- rocs -t <target_OCS> -k "mark 56" ----

* appname_:keyident : A value of this form selects keys by their internal application name and ident. You must supply at least one of appname or keyident, but you can use wildcard patterns for either or both in order to select all matching keys. An example of usage is: + [source] ---- rocs -t <target_OCS> --keys="simple:simplekey" ----

* hash keyhash: A value of this form selects the key with the given key hash. An example of usage is: + [source] ---- rocs -t <target_OCS> --keys="hash e364[…​]" ----

--cardset cardset-spec

A value of this form selects all keys protected by a given card set.

-t, --target=CARDSET-SPEC

Specifies the cardset to recover (to create new passphrases for). You can use this option multiple times to specify multiple cardsets.

See -c, --cardset=CARDSET-SPEC for the available forms for the CARDSET-SPEC value.

Option to address the HSM

-m, --module=MODULE

Module to use for recovery (creating new passphrases).

Help options

-h, --help

Displays help for rocs.

-u, --usage

Displays a brief usage summary for rocs.

-v, --version

Displays the version number of the Security World Software that deploys rocs.

rocs interactive mode commands

At the rocs prompt, you can use the following commands.

You can specify a command by typing enough characters to identify the command uniquely. For example, for the status command, you can type st and then press Enter.
Command Description

help

Displays a list of available commands with brief usage messages and a list of other help topics. With an argument, help shows detailed help information about a given topic.

help intro

Displays a brief step-by-step guide to using rocs.

list cardsets

Lists the OCSs and softcards in the current Security World.

For example:

No.
Name                    Keys (recov) Sharing
 1 test                    6 (6)        3 of 5; 20 minute timeout
 2 test2                   3 (2)        2 of 3
 3 test3                   1 (1)        1 of 1; persistent

In this output:

  • No.: The card set or softcard number, which you can use to identify this card set in rocs commands.

  • Name: The OCS or softcard name.

  • Keys: The number of keys protected by this OCS or softcard.

  • (recov): The number of keys protected by this OCS or softcard.

  • Sharing: The K of N parameters for this OCS.

  • persistent: The OCS is persistent and does not have a time-out set.

  • ### minute timeout: The OCS is persistent and has a time-out set.

list keys

Lists the keys in the current Security World, as in the following example:

No.
Name                     App        Protected by
 1 rsa-test                 hwcrhk     module
 2 Id: uc63e0ca3cb032d71c1c pkcs11     test2
R 3 Server-Cert              pkcs11     test --> test2
 4 Id: uc63e0ca3cb032d71c1c pkcs11     test --> test3
 5 Server-Cert              pkcs11     module (test ---> fred2)

In this output:

  • No.: The key number, which you can use in mark and unmark commands.

  • Name: The key name.

  • App: The application with which the key is associated.

  • Protected by: This indicates the protection method.

Protection methods:

  • module: Key protected by the Security World.

  • <name>, for example test2: Key protected by the named OCS or softcard.

  • <name> --> <name2>, for example test -→ test2: Key protected by the OCS or softcard name1 marked for recovery to OCS or softcard name2.

  • module (<name>): PKCS #11 public object.

    These are protected by the Security World but associated with a specific OCS or softcard.

  • module (<name> --> <name2>), for example module (test --→ fred2): PKCS #11 public object marked for recovery.

mark <key-spec>

Marks the listed keys that are to be recovered to the target OCS or softcard. You can mark one or more keys by number, ident, OCS or softcard, or hash.

To mark more than one key at a time, ensure that each key-spec is separated from the other by spaces, for example:

[source] ---- mark key-spec1 key-spec2 key-spec3 ----

If you have not selected a target OCS or softcard, or if rocs cannot parse the key-spec, then rocs displays an error message.

You can mark and remark the keys to be recovered to various target OCSs or softcards. Remarking a key displaces the first target in favor of the second target.

[NOTE] Keys protected by an OCS can only be recovered to another OCS, and not to a softcard. Likewise, softcard-protected keys can only be recovered to another softcard, and not to an OCS.

module <number>

Selects the hardware security module to be used. The module <number> must correspond to a hardware security module in the current Security World. If the hardware security module does not exist, is not in the Security World, or is otherwise unusable, then rocs displays an error message and does not change to the selected module.

quit

Allows you to leave rocs. If you attempt to quit when you have recovered keys but have not saved them, rocs displays a warning.

recover

Transfers the marked keys to their target OCSs or softcards. This operation is not permanent until you save these keys by using the save command.

rescan

Updates the card set and key information.

revert <key-spec>

Returns keys that have been recovered, but not saved, to being protected by the original protection method. If the selected keys have not been recovered, rocs displays an error message.

save [<key-spec>]

Writes the new key blobs to disk. If you specify <key-spec> values, only those keys are saved. Otherwise, all recovered keys are saved.

status

Lists the currently selected hardware security module and target OCS or softcard.

target <cardset-spec>

Sselects a given OCS or softcard (<cardset-spec>) as the target. You can specify the card set or softcard name, the number returned by list cardsets, or the hash.

unmark <key-spec>

Uunmarks the listed keys. Unmarked keys are not recovered.