Key generation options and parameters

This appendix describes the various options and parameters that you can set when running the generatekey utility to control the application type and other properties of a key being generated.

For information about generating keys with the generatekey utility, see Generating keys with the command line.

Key application type (APPNAME)

The APPNAME parameter specifies the name of the application for which generatekey can generate keys. Specifying an application can restrict your choice of key type. A value for APPNAME must follow any OPTIONS and must precede any parameters specified for the key:

Parameter Description

simple

Specifying the simple application type generates an nShield-native key. No special action is taken after the key is generated.

custom

Specifying the custom application type generates a key for custom applications that require the key blob to be saved in a separate file.

Specifying custom also causes the generation of a certificate request and self-signed certificate. However, we recommend that you specify the simple (instead of custom) application type whenever possible.

pkcs11

Specifying the pkcs11 application type generates keys that are formatted for use with PKCS #11 applications and are given a suitable identifier. The set of possible supported key types is currently limited to:

  • DES3

  • DH

  • DSA

  • ECDH

  • ECDSA

  • Ed25519

  • HMACSHA1

  • RSA

  • Rijndael (AES)

  • X25519

Some key types are only available if the features that support them have been enabled for the module, if the Security World is not compliant with FIPS 140 Level 3, or if you do not set the --no-verify option.

embed

Specifying the embed application type generates a PEM-format RSA/DSA key file that points to a key in NFAST_KMDATA so a software application can then use the HSM-protected key.

In applications that use Security World software older than v12.60 and would use the legacy OpenSSL CHIL engine with hwcrhk:

  • The plainname specified in the generatekey command is used as the prefix for all 3 generated files (.key, _req, _selfcert)

  • .key is appended to all 3 files

  • The embedsavefile specified in the generatekey command is the destination for all 3 files

In applications that use v12.60 or later Security World software :

  • The plainname specified in the generatekey command is used as the prefix for only the .key file, the prefix for the _req and _selfcert file is embed<hash>

  • .key is not appended to the _req and _selfcert files

  • The embedsavefile is the destination only for the .key file, _req and _selfcert are created in the directory from which generatekey was run from

kpm

Specifying the kpm application type generates a key for delivery by an nForce Ultra key server. The generatekey utility automatically creates a special ACL entry that permits a kpm to be delivered to an nForce Ultra’s enrolled internal hardware security module.

seeinteg

Specifying the seeinteg application type generates an SEE integrity key. The DSA, RSA, ECDSA and KCDSA algorithms are supported. SEE integrity keys are always protected by an OCS and cannot be imported. You cannot retarget an existing key as an SEE integrity key.

seeconf

Specifying the seeconf application type generates an SEE confidentiality key. Both the Triple DES and AES algorithms are supported for this key type. SEE confidentiality keys are module-protected by default and cannot be imported. You cannot retarget an existing key as an SEE confidentiality key.

Key properties (NAME=VALUE)

The NAME=VALUE syntax is used to specify the properties of the key being generated.

If a parameter’s argument contains spaces, you must enclose the argument within quotation marks (" ").

You can supply an appropriate VALUE for the following NAME options:

Option Description

alias

The VALUE for alias specifies an alias to assign to the key.

assigned

The VALUE for assigned specifies if the generated key is to be Assigned as defined by nShield Solo XC Common Criteria Evaluated Configuration Guide. This is only relevant in common-criteria-cmts mode Security Worlds and the key must be protected with a non-recoverable softcard or token. If set to yes the ACL of the generated key will match the definition of an Assigned key in nShield Solo XC Common Criteria Evaluated Configuration Guide and will be verified as an Assigned key by nfkmverify. The default is no.

blobsavefile

When using the custom application type, the VALUE for blobsavefile specifies a file name of the form FILENAME_req.ext to which the key blob is saved. Additionally, a text file containing information about the key is saved to a file whose name has the form ROOT_inf.txt; for asymmetric key types, the public key blob is also saved to a file whose name has the form ROOT_pub.EXT.

cardset

The VALUE for cardset specifies an OCS that is to protect the key (if protect is set to token). In interactive mode, if you do not specify an OCS, you are prompted to select one at card-loading time. The default is the OCS to which the card currently inserted in the slot belongs (or the first one returned by nfkminfo).

certreq

Setting certreq enables you to generate a certificate request when generating a PKCS #11 key (RSA keys only). The default behavior is to not generate a certificate request.

To generate a certificate request you must set the VALUE for certreq to yes, which makes generatekey prompt you to fill in the extra fields required to generate a key with a certificate request. The resultant certificate request is saved to the current working directory with a file name of the form FILENAME req.ext (where FILENAME is a name of your choice).

An extra file with a name of the form FILENAME.ext is also generated for use as a pseudo-key-header. This file can be removed after the certificate request has been generated. You can use certreq with the --retarget option to generate a self-signed certificate for an existing key.

checks

For RSA key generation only, this specifies the number of checks to be performed. Normally, you should leave VALUE empty to let the module pick an appropriate default.

curve

For ECDH and ECDSA key generation only, the VALUE for curve specifies which curves from the supported range to use. Supported curves are: ANSIB163v1, ANSIB191v1,BrainpoolP160r1, BrainpoolP160t1, BrainpoolP192r1, BrainpoolP192t1, BrainpoolP224r1, BrainpoolP224t1, BrainpoolP256r1, BrainpoolP256t1, BrainpoolP320r1, BrainpoolP320t1, BrainpoolP384r1, BrainpoolP384t1, BrainpoolP512r1, BrainpoolP512t1, NISTP192, NISTP224, NISTP256, NISTP384, NISTP521, NISTB163, NISTB233, NISTB283, NISTB409, NISTB571, NISTK163, NISTK233, NISTK283, NISTK409, NISTK571, SECP160r1 and SECP256k1

embedconvfile

The VALUE for embedconvfile specifies the name of the PEM file that contains the RSA key to be converted.

embedsavefile

When using the embed application type, the VALUE for embedsavefile specifies the name for the file where the fake RSA private key is to be saved. The file has the same syntax as an RSA private key file, but actually contains the key identifier rather than the key itself, which remains protected.

A certificate request and a self-signed certificate are also written. If the filename is ROOT.EXT then the request is saved to ROOT_req.EXT and the self-signed certificate is saved to ROOT_selfcert.EXT.

from-application

When retargeting a key, the VALUE for from-application specifies the application name of the key to be retargeted. Only applications for which at least one key exists are acceptable.

from-ident

When retargeting a key, the VALUE for from-ident specifies the identifier of the key to be retargeted (as displayed by the nfkminfo command-line utility).

hexdata

The VALUE for hexdata specifies the hex value of DES or Triple DES key to import. The hex digits are echoed to the screen and can appear in process listings if this parameter is specified in the command line.

ident

The VALUE for ident specifies a unique identifier for the key in the Security World. For applications of types simple, this is the key identifier to use. For other application types, keys are assigned an automatically generated identifier and accessed by means of some application-specific name.

The following characters are allowed in key IDs:

  • digits 0-9

  • lower-case letters a-z

  • hyphen (-)

keystore

The VALUE for keystore specifies the file name of the key store to use. This must be an nShield key store.

keystorepass

The VALUE for keystorepass specifies the password to the key store to use.

logkeyusage

The VALUE for logkeyusage specifies if usage of the generated key in cryptographic operations is subject to audit logging. If set to yes the ACL of the generated key will predicate audit-logging entries to be made for cryptographic usages of the key. The default is no.

module

The VALUE for module specifies a module to use when generating the key. If there is more than one usable module, you are prompted to supply a value for one of them. The default is the first usable module (one in the current Security World and in the operational state).

You can also specify a module by setting the --module option.

paramsreadfile

The VALUE for paramsreadfile specifies the name of the group parameters file that contains the discrete log group parameters for Diffie-Hellman keys only. This should be a PEM-formatted PKCS#3 file. If a VALUE for paramsreadfile is not specified, the module uses a default file.

pemreadfile

The VALUE for pemreadfile specifies the name of the PEM file that contains the key to be imported. When importing an RSA key, this is the name of the PEM-encoded PKCS #1 file to read it from. Password-protected PEM files are not supported.

plainname

The VALUE for plainname specifies the key name within the Security World. For some applications, the key identifier is derived from the name, but for others the name is just recorded in and not used otherwise.

protect

The VALUE for protect specifies the protection method, which can be module for security-world protection, softcard for softcard protection or token for Operator Card Set protection. The default is token, except for seeconf keys, where the default is module. seeinteg keys are always token-protected. The softcard option is only available when your system has at least one softcard present.

pubexp

For RSA key generation only, the VALUE for pubexp specifies (in hexadecimal format) the public exponent to use when generating RSA keys. We recommend leaving this parameter blank unless advised to supply a particular value by Support.

recovery

The VALUE for recovery enables recovery for this key and is only available for card-set protected keys in a recovery-enabled world. If set to yes, the key is recoverable. If set to no, key is not recoverable. The default is yes. Non-recoverable module-protected keys are not supported.

seeintegname

If present, the VALUE for seeintegname identifies a seeinteg key. The ACL of the newly generated private key is modified to require a certificate from the seeinteg key for its main operational permissions, such Decrypt and Sign (DuplicateHandle, ReduceACL, and GetACL are still permitted without certification.)

If you use seeintegname to specify a key that has been recovered with the rocs utility, you must also use the -N option with generatekey.

selfcert

The VALUE for selfcert enables you to generate a self-signed certificate when generating a PKCS #11 key (RSA keys only). To generate a self-signed certificate request you must set selfcert to yes, which makes generatekey prompt you to fill in the extra fields required to generate a key with a self-signed certificate. The resultant certificate is saved to the current working directory with a file name of the form FILENAME.ext. You can use this parameter with the --retarget option to generated a self-signed certificate for an existing key.

size

For key types with variable-sized keys, the VALUE for size specifies the key size in bits. The range of allowable sizes depends on the key type and whether the --no-verify option is used. The default depends on the key type; for information on available key types and sizes, see Cryptographic algorithms. This parameter does not exist for fixed-size keys, nor for ECDH and ECDSA keys which are specified using curve.

strict

For DSA key generation only, setting the VALUE for strict to yes enables strict verification, which also limits the size to 2048 or 3072 bits. The default is no.

type

The VALUE for type specifies the type of key. You must usually specify the key type for generation and import (though some applications only support one key type, in which case you are not asked to choose). Sometimes the type must also be specified for retargeting; for information on available key types and sizes, see Cryptographic algorithms. The --verify option limits the available key types.

x509country

The VALUE for x509country specifies a country code, which must be a valid 2-letter code, for the certificate request.

x509dnscommon

The VALUE for x509dnscommon specifies a site domain name, which can be any valid domain name, for the certificate request.

x509email

The VALUE for x509email specifies an email address for the certificate request.

x509locality

The VALUE for x509locality specifies a city or locality for the certificate request.

x509org

The VALUE for x509org specifies an organization for the certificate request.

x509orgunit

The VALUE for x509orgunit specifies an organizational unit for the certificate request.

x509province

The VALUE for x509province specifies a province for the certificate request.

xsize

The VALUE for xsize specifies the private key size in bits when generating Diffie-Hellman keys. The defaults are 256 bits for a key size of 1500 bits or more or 160 bits for other key sizes.

Available key properties by action/application

The following table shows which actions (generate, import, and retarget) are applicable to the different NAME options:

Property generate import retarget

alias

X

X

X

blobsavefile

X

X

X

cardset

X

X

certreq

checks

X

curve

X

embedconvfile

X

embedsavefile

X

X

X

from-application

X

from-ident

X

hexdata

X

ident

X

X

keystore

X

X

X

keystorepass

X

X

X

module

X

X

nvram

X

X

paramsreadfile

X

pemreadfile

X

plainname

X

X

X

protect

X

X

pubexp

X

qsize

X

recovery

X

X

seeintegname

selfcert

size

X

strict

X

type

X

x509country

X

X

X

x509dnscommon

X

X

X

x509email

X

X

X

x509locality

X

X

X

x509org

X

X

X

x509orgunit

X

X

X

x509province

X

X

X

xsize

X

The following table shows which applications are applicable to the different NAME options:

Property custom embed hwcrhk pkcs 11 seeconf seeinteg seessl simple kpm

alias

blobsavefile

X

cardset

X

X

X

X

X

X

certreq

X

checks

X

X

X

X

X

X

curve

X

X

X

X

X

X

X

embedconvfile

X

embedsavefile

X

X

from-application

X

X

X

X

X

X

from-ident

X

X

X

X

X

X

hexdata

X

X

X

X

X

ident

X

X

X

keystore

keystorepass

module

X

X

X

X

X

X

X

nvram

X

X

X

X

X

paramsreadfile

X

X

X

X

X

X

X

pemreadfile

X

X

X

X

plainname

X

X

X

X

X

X

X

X

protect

X

X

X

X

X

X

X

X

X

pubexp

X

X

X

X

X

X

qsize

X

X

X

X

X

X

recovery

X

X

X

X

X

X

X

X

seeintegname

X

X

X

selfcert

X

size

X

X

X

X

X

X

X

X

X

strict

X

X

X

X

X

type

X

X

X

X

X

X

X

X

X

x509country

X

X

x509dnscommon

X

X

x509email

X

X

x509locality

X

X

x509org

X

X

x509orgunit

X

X

x509province

X

X

xsize

X

X

X

X

X