Key generation options and parameters

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.

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:

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.

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:

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

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.

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.

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

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.

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.

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

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.

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.

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

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

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.

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.

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

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.

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:

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

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

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.

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

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.

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 kmdata (Linux) or %NFAST_KMDATA% (Windows) and not used otherwise.

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.

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.

For MLDSA, MLKEM and SLHDSA key generation only, the VALUE for scheme specifies the parameter set to use. See Parameter sets for Post-Quantum key types below for possible values.

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.

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

seeintegname can now identify more than one seeinteg key, in the form of a list of key idents separated by spaces or commas.

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.

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.

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.

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.

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.

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

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

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

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

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

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

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

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.