Working with keys

This chapter explains how to use the facilities we provide to work with keys. There is often more than one way of performing a particular task. The methods available for working with keys are:

  • KeySafe

  • generatekey and related utilities

Generating keys

Whenever possible, generate a new key instead of importing an existing key. Because existing keys have been stored in a known format on your hard disk, there is a risk that the existing key has been compromised. Key material can also persist on backup media.

Some applications can generate keys directly.

When you attempt to generate keys for a Security World that complies with FIPS 140 Level 3, you are prompted to insert an Administrator Card or Operator Card. You may need to specify to the application, the slot you are going to use to insert the card. You need to insert the card only once in a session.

For softcard protected key generation, you must use an Operator Card Set.

Generating a key creates both a key and a certificate request for the following application types:

  • embed (OpenSSL)

  • kpm

These requests are generated in PKCS #10 format with base-64 encoding.

Generating keys using the command line

Keys are generated using the command line with the generatekey utility. The --generate option creates a new key on the host computer that is protected either by the module or by an Operator Card set from the Security World. No key material is stored in an unencrypted form on the host computer.

When you generate a key with generatekey, choose a new identifier for the key and use whichever application type is appropriate. The key identifier can only contain digits, lowercase ASCII letters, and hyphens (-).

Any uppercase letters you enter in the key identifier are converted to lowercase when the key is generated.

You can use generatekey in two ways:

  • In interactive mode, by issuing commands without parameters and supplying the required information when prompted by the utility

  • In batch mode, by supplying some or all of the required parameters using the command line (generatekey prompts interactively for any missing but required parameters).

In interactive mode, you can input abort at any prompt to terminate the process.

Batch mode is useful for scripting. In batch mode, if any required parameters are omitted, generatekey does not prompt for the missing information but instead will either use available defaults or fail. If you specify one or more parameters incorrectly, an error is displayed and the command fails.

If the Security World was created with audit logging selected then you can request that the usage of a key for cryptographic operations is logged in the audit log. By default only key generation and destruction is logged. For further information see Audit Logging.

To generate a key, use the command:

generatekey --generate [OPTIONS] <APPNAME> [<NAME>=<VALUE> ...]

In this command:

  • --generate option specifies that this instance of generatekey is generating a key. Other options can be specified to perform tasks such as importing or retargeting keys. To see a list of options run the command generatekey --help.

  • the <APPNAME> parameter specifies the name of the application for which the key is to be generated. For details of the available application types (APPNAME), Key application type (APPNAME).

  • The <NAME>=<VALUE> syntax is used to specify the properties of the key being generated. For details of the available application types (APPNAME), see Key properties (NAME=VALUE).

For details of the available application types (APPNAME) and parameters that control other key properties (NAME=VALUE), see Key generation options and parameters and parameters.

In interactive mode, generatekey prompts you for any required parameters or actions that have not been included in the command. When you give the command:

  1. Enter parameters for the command, as requested. If you enter a parameter incorrectly, the request for that information is repeated and you can re-enter the parameter.

  2. When all the parameters have been collected, generatekey displays the final settings. In a FIPS 140 Level 3 compliant Security World, you are prompted to insert a card for FIPS authorization if no such card is present.

  3. If prompted, insert an Administrator Card or an Operator Card from the current Security World.

  4. If you want to protect the key with an OCS, you are prompted to insert the relevant cards and input passphrases, as required.

Example of key generation with generatekey

To generate a simple RSA key in batch mode, protected by module protection, use the command:

generatekey --generate --batch simple type=rsa size=2048 plainname=keya ident=abcd certreq=yes

The generatekey utility prompts you to insert a quorum of Operator Cards from the operatorone OCS. After you have inserted the appropriate number of cards, generatekey generates the key.

Although it is not explicitly specified, the created key is recoverable by default if OCS and softcard replacement is enabled for the Security World.

Generating keys with KeySafe

In order to generate a key with KeySafe, follow these steps:

  1. Start KeySafe. (For an introduction to KeySafe and for information on starting the software, see Using KeySafe.)

  2. Click the Keys menu button, or select Keys from the Manage menu. KeySafe takes you to the Keys panel, which shows the keys in the Security World.

  3. Click the Create button to open the Generate Key panel.

  4. Select an application with which you want to use your key from the list, and then click the Next button. KeySafe takes you to the Key Generation Parameters panel.

  5. Select and enter your desired parameters for key generation.

    The types of information that you need to provide on the Key Generation Parameters panel differs slightly depending on the application you selected on the Generate Key panel.

  6. When you have supplied your desired key generation parameters, click the Commit button.

    In order to generate a key protected by a FIPS 140 Level 3 compliant Security World, you need authorization from an Operator Card or Administrator Card from the current Security World. Follow the onscreen instructions.

  7. If you choose to generate a key that is protected by a smart card or softcard, KeySafe takes you to a panel from which you can load the protecting card or softcard. Follow the onscreen instructions, inserting any necessary Operator Cards and supplying any passphrases as needed.

  8. KeySafe displays a message indicating that the key has been successfully generated. Click the OK button.

  9. KeySafe returns you to the Generate Key panel, from which you can generate another key or choose another operation.

Generating NVRAM-stored keys

NVRAM key storage provides a mechanism for generating keys stored in a module’s nonvolatile memory and hence within the physical boundary of an nShield module. You can store only a few keys in this way: the number depends on the memory capacity of the module, the size of the key and whether the key has recovery data associated with it.

We recommend that you do not store keys in NVRAM unless you must do so to satisfy regulatory requirements. NVRAM key storage was introduced only for users who must store keys within the physical boundary of a module to comply with regulatory requirements. NVRAM-stored keys provide no additional security benefits and their use exposes your ACS to increased risk. Storing keys in nonvolatile memory also reduces load-balancing and recovery capabilities. Because of these factors, we recommend you always use standard Security World keys unless explicitly required to use NVRAM-stored keys.

When you generate an NVRAM-stored key, you must have sufficient nonvolatile memory available in the module or the command fails.

You need backup and recovery procedures, which must be consistent with regulatory requirements, to protect your NVRAM-stored keys. Do NOT use Remote Administration to back-up keys to a smart card, as, in transit, the keys would not be physically protected from access by the host system.
An NVRAM-stored key can only be loaded successfully by using the preload command-line utility on the generating module. Attempts to load such a key on other modules that have NVRAM fail with UnknownID errors.

We provide the nvram-backup utility to enable the copying of files, including NVRAM-stored keys, between a module’s nonvolatile memory and a smart card.

Importing keys

Importing a key takes an unprotected key stored on the host and stores it in the Security World in encrypted form.

We recommend generating a new key (or retargeting a key from within the Security World) instead of importing an existing key whenever possible. The import operation does not delete any copies of the key material from the host, and because existing keys have been stored in a known format on your hard disk (and key material can persist on backup media), there is a risk that an existing key has been compromised. It is your responsibility to ensure any unprotected key material is deleted. If a key was compromised before importation, then importing it does not make it secure again.

The following key types can be imported by the tools we provide:

  • RSA keys in PEM-encoded PKCS #1 format (from a file). The PEM key that contains the key to import must not require a passphrase.

  • DES, DES2 and Triple DES keys (entered in hex).

You cannot import keys into a Security World that complies with FIPS 140 Level 3. Attempting to import keys into a FIPS 140 Level 3 Security World returns an error.

This request is a PKCS #10 format request in base-64 encoding.

Importing keys from the command line

You can import keys using the generatekey utility. To import a key, give the command:

generatekey --import [<OPTIONS>] <APPNAME> [<NAME>=<VALUE> ...]

This command uses the following options:

Option Description

--import

This option specifies key importation.

<OPTIONS>

You can specify particular options when running generatekey that control details of key importation.

<APPNAME>

This option specifies the name of the application for which the key is to be imported. This must be an application for which generatekey can generate keys.

<NAME>=<VALUE>

This specifies a list of parameters for the application.

For RSA keys, you can include pemreadfile=filename in the command to specify the file name of the PEM file that contains the key. Otherwise, you are prompted for this information during import.

In interactive mode, you are prompted for any required parameters or actions that have not been included in the command:

  • Enter parameters, as requested. If you enter a parameter incorrectly, the request for that information is repeated and you can re-enter the parameter.

  • If you want to protect the key with an OCS, you are prompted to insert the relevant cards and input passphrases, as required.

  • If prompted, insert an Administrator Card or an Operator Card from the current Security World.

Example of key importation with generatekey

To import an RSA key stored in C:\projects\key.pem for use with an nShield native application and protect it with the Security World, use the command:

generatekey --generatekey --import simple pemreadfile=C:\projects\key.pem plainname=importedkey ident=abc protect=module

In this example, generatekey requires you to input RSA for the key type.

Although not explicitly specified, this key is, by default, recoverable if OCS and softcard replacement is enabled for the Security World.

Importing keys with KeySafe

Any user who has write access to the directory that contains the Security World can import a key.

In order to import a key with KeySafe, follow these steps:

  1. Start KeySafe. (For an introduction to KeySafe and for information on starting the software, see Using KeySafe.)

  2. Click the Keys menu button, or select Keys from the Manage menu. KeySafe takes you to the Keys panel.

  3. Click Import to open the Import Key panel.

  4. Select the application associated with the key that you want to import, and then click the Next button. KeySafe takes you to the Key Import Parameters panel.

  5. Select and enter the desired parameters for the key that you want to import.

    The types of information that you need to provide on the Key Import Parameters panel will differ slightly depending on the application you selected on the Import Key panel.

  6. When you have supplied parameters for the key that you want to import, click the Commit button.

  7. If you choose to import a key that is protected by a smart card, KeySafe takes you to the Load Operator Card Set panel. Follow the onscreen instructions, inserting the required number of Operator Cards and supplying any passphrases as needed.

  8. KeySafe displays a message indicating that the key has been successfully imported. Click the OK button.

  9. KeySafe returns you to the Import Key panel, from which you can import another key or choose another operation.

Listing supported applications with generatekey

To list supported applications, use the command:

generatekey --list-apps

Retargeting keys with generatekey

The --retarget option to takes an existing key in the Security World and makes it available for use by another application as if it had been expressly generated for use by that application. Because no key material is exposed during retargeting, this operation is as secure as generating a new key.

When you retarget a key, generatekey does not remove the original key from the Security World. If required, you can use KeySafe to discard the original key.

When you retarget a key, you cannot change its protection method. You cannot change the key from module-protected to card-protected, or from card-protected to module-protected.

To retarget a key, use the command:

generatekey --retarget [<OPTIONS>] <APPNAME> [from-application=<appname>]
[from-ident=<keyident>]

In this command:

Option Description

--retarget

This option specifies key importation.

<OPTIONS>

This option specifies any options to include when the command is run. Run the command generatekey --help for details about the available options.

<APPNAME>

This option specifies the name of the application for which the key is to be generated. This must be an application for which generatekey can generate keys.

from-application=<appname>

This option specifies the name of the application with which the key is currently associated.

from-ident=<keyident>

This option specifies the identifier of the key to be retargeted. You can find this identifier by using the nfkminfo command-line utility.

If generatekey cannot identify the key type for retargeting, you are prompted to specify the key type. Input the key type and press Enter.

Viewing keys

You can view existing keys in the Security World using KeySafe, or the nfkminfo command-line utility.

Viewing keys with KeySafe

In order to view a list of keys with KeySafe, follow these steps:

  1. Start KeySafe. (For an introduction to KeySafe and for information on starting the software, see Using KeySafe.)

  2. Click the Keys menu button, or select Keys from the Manage menu. KeySafe takes you to the Keys panel, which lists all the keys in the Security World. It displays the name of the key, the application for which it was created, the protection method that was used and whether the key is stored in NVRAM.

    If you click a key’s listing, KeySafe displays additional information about that key, for example, the application with which the key is used, whether or not the key is recoverable, and the key’s name, creation date, hash, instance, and copy ID.

    From the Keys panel, you can choose to:

Viewing keys using the command line

The nfkminfo command-line utility is used to list keys. To list the keys that have been created in the current Security World, use one of the following commands:

nfkminfo -k [<APPNAME>[<IDENT>]]
nfkminfo -l [<APPNAME>[<APPNAME>...]]

The -k|--key-list option lists keys only. The -l|--name-list option lists keys and their names.

With either option, <APPNAME> is an optional application name. If you specify an application name, nfkminfo lists only the keys for that application. Commonly, <APPNAME> is often one of:

  • custom

  • embed

  • pkcs11

  • kpm

  • kps

  • mscapi

  • seeconf

  • seeinteg

  • simple

You can also specify your own application names for APPNAME as appropriate to your system.

For example, user-defined application names can be created by using the nfkm library to generate arbitrary keys.

With the --name-list option, <IDENT> is the key identifier.

The command nfkminfo --key-list returns output of the form:

Key summary - 4 keys:
 AppName appname    Ident <ident> AppName <appname>
Ident <ident> AppName <appname>
Ident <ident> AppName <appname>                Ident <ident>

To list information about a specific key, specify the --key-list option with an application and key identifier:

nfkminfo --key-list <appname> <ident>

This command returns output of the form:

Key AppName <appname> Ident <ident> BlobKA length   752
 BlobPubKA length      316
 BlobRecoveryKA length 868
 name                  "name"
 hash                  hash recovery              Enabled
 protection            CardSet
 other flags           PublicKey +0x0
 cardset               hash_ktBlobKA
 format                6 Token
 other flags           0x0
 hkm                   hash_km hkt                hash_kt hkr       none
BlobRecoveryKA
 format                8 Indirect
 other flags           0x0
 hkm                   none
 hkt                   none
 hkr                   hash_krBlobPubKA
 format                5 Module
 other flags           0x0
 hkm                   hash_km hkt                none
 hkr                   none
No extra entries

To list keys and names, specify the --name-list option. The command nfkminfo --name-list returns output of the form:

Key summary - 30 keys
in format key_<appname>_<ident> '<name>')
  key_appname_ident'name '
  key_appname_ident'name '
  key_appname_ident'name '
  key_appname_ident'name '
  key_appname_ident'name '
  key_appname_ident'name '
  key_appname_ident'name '

Verifying Key Generation Certificates with nfkmverify

The nfkmverify command-line utility verifies key generation certificates. You can use nfkmverify to confirm how a particular Security World and key are protected. It also returns some information about the Security World and key.

The nfkmverify utility compares the details in the ACL of the key and those of the card set that currently protects the key.

A key that has been recovered to a different card set shows a discrepancy for every respect that the new card set differs from the old one. For example, a key recovered from a 2-of-1 card set to a 1-of-1 card set has a different card-set hash and a different number of cards, so two discrepancies are reported. The discrepancy is between the card set mentioned in the ACL of the key and the card set by which the key is currently protected (that is, the card set mentioned in the key blobs).

A key that has been transferred from another Security World shows discrepancies and fails to be verified. Entrust recommends that you verify keys in their original Security World at their time of generation.

If you must replace your Security World or card set, Entrust recommends that you generate new keys whenever possible. If you must transfer a key, perform key verification immediately before transferring the key; it is not always possible to verify a key after transferring it to a new Security World or changing the card set that protects it.

Usage

To verify the key generation certificates from the command line, run the command:

nfkmverify [-f|--force] [-v|--verbose] [-U|--unverifiable] [-m|--module=MODULE] [appname ident [appname ident [...]]]

Optionally, the command can also include the following:

Option Description

-h|--help

This option displays help for nfkmverify.

-V|--version

This option displays the version number for nfkmverify.

-u|--usage

This option displays a brief usage summary for nfkmverify.

-m|--module=MODULE

This option performs checks with module MODULE.

-f|--force

This option forces display of an output report that might be wrong.

-U|--unverifiable

This option permits operations to proceed even if the Security World is unverifiable.

If you need the -U|--unverifiable option, there may be some serious problems with your Security World.

-v|--verbose

This option prints full public keys and generation parameters.

-C|--certificate

This option checks the original ACL for the key using the key generation certificate. This is the default.

-L|--loaded

These options check the ACL of a loaded key instead of the generation certificate.

-R|--recov

This option checks the ACL of the key loaded from the recovery blob.

--allow-dh-unknown-sg-group

This option allows an operation to proceed even if a Diffie-Hellman key is using an unrecognized Sophie-Germain group.

Discarding keys

Discarding a key deletes the information about the key from the host disk. This option is only available in KeySafe.

If you have backup media, you can restore the information and the key becomes usable again. Likewise, if you have copies of the Security World data on several computers, erasing the data on one computer does not remove it from any other computer.

To destroy a key permanently you must either erase the OCS that is used to protect it or erase the Security World completely. There are no other ways to destroy a key permanently.

Restoring keys

We do not supply tools for restoring a key that has been discarded. However if you have kept a backup of the host data for the Security World, you can restore a key from the backup data.

If you have NVRAM-stored keys, you must additionally ensure you have a backup of the key data stored on the relevant modules.