nShield PKCS #11 library environment variables

The all parameter overrides all security checks and has the same effect as supplying all the other CKNFAST_OVERRIDE_SECURITY_ASSURANCES parameters except the none parameter. Using the all parameter prevents the library from performing any of the security checks and allows the library to perform potentially insecure operations. This parameter cannot be used with any other parameters.

The none parameter does not override any of the security checks and has the same effect as supplying no parameters. Using the none parameter allows the library to perform all security checks and warn about potentially insecure operations without performing them. This parameter cannot be used with any other parameters.

The tokenkeys parameter permits applications to request that insecure keys are stored long-term by the cryptographic hardware and library.

Some PKCS #11 applications create short-term session keys as long-term objects in the cryptographic provider, for which strong protection by the HSM is not important. Therefore, provided that you intend to create long-term keys, the need to set this token does not always indicate a potential problem because the longterm keys restriction is triggered automatically. If you set the tokenkeys parameter, ensure that your Quality Assurance process tests all of your installation’s functionality at least 48 hours after the system was set up to check that the key lifetimes are as expected.

When the tokenkeys parameter is set, the effect on the PKCS #11 library is to permit insecure Token keys. By default, any attempts to create, generate, or unwrap insecure keys with CKA_TOKEN=true fails with CKR_TEMPLATE_INCONSISTENT and a log message that explains the insecurity. When tokenkeys is included as a parameter for CKNFAST_OVERRIDE_SECURITY_ASSURANCES, attempts to create, generate, or unwrap insecure keys with CKA_TOKEN=true are allowed.

The longterm parameter permits an insecure key to be used for days after it was created. Usually insecure keys may not be used more than 48 hours after their creation. If days is not specified, there is no time limit.

When the longterm parameter is set, the PKCS #11 API permits the use of the following functions with an insecure key up to the specified number of days after its creation:

By default these functions fail with CKR_FUNCTION_FAILED, or CKR_KEY_FUNCTION_NOT_PERMITTED, and a log message that explains the insecurity of these functions when used with an insecure private or secret key more than 48 hours after the creation of the key as indicated by time() on the host.

When the longterm parameter is set, the functions C_SignInit, C_VerifyInit, C_EncryptInit, and C_DecryptInit check the CKA_CREATION_DATE against the current time.

The explicitness parameter permits applications to create insecure keys without explicitly recognizing that they are insecure. An insecure key is a key that is deemed sensitive, but can be wrapped and extracted from the HSM by any untrusted key. A secure key must have the CKA_WRAP_WITH_TRUSTED attribute.

Unless the explicitness parameter is set, attempts to create, generate, or unwrap insecure keys with CKA_SENSITIVE=true, or to set CKA_SENSITIVE=true on an existing key, fail by default with CKR_TEMPLATE_INCONSISTENT and a log message explaining the insecurity. However, when the explicitness parameter is set, these operations are allowed.

The import parameter allows keys that are to be imported into the HSM’s protection from insecure external sources to be treated as secure, provided that the application requests security for them. Usually, the library treats imported keys as insecure for the purposes of checking the security policy of the application. Even though the imported copy may be secure, insecure copies of the key may still exist on the host and elsewhere.

If you are migrating from software storage to hardware protection of keys, you must enable the import parameter at the time of migration. You can disable import again after migrating the keys.

When the import parameter is set, the PKCS #11 API treats keys that are imported through C_CreateObject or C_UnwrapKey as secure (provided there is no other reason to treat them as insecure). By default, keys which are imported through C_CreateObject or C_UnwrapKey without this option in effect are marked as being insecure. Only the setting of the parameter at the time of import is relevant.

The wrapping_crypt parameter allows you to create keys with insecure combinations of wrap/unwrap and encrypt/decrypt operations.

By default, when wrapping_crypt is not supplied as a parameter for CKNFAST_OVERRIDE_SECURITY_ASSURANCES, trying to create a key with either CKA_UNWRAP=true or CKA_WRAP=true and CKA_DECRYPT=true or CKA_ENCRYPT=true will fail with CKR_TEMPLATE_INCONSISTENT.

Combinations such as wrap+encrypt or unwrap+encrypt are prohibited because for some mechanisms (e.g. counter mode), encrypt and decrypt are the same operation, so allowing encrypt is functionally the same as allowing decrypt.

When a key is transferred into the HSM in encrypted form, the key is usually treated as insecure unless the key that was used for the decryption only allows the import and export of keys and not the decryption of arbitrary messages. This behavior is necessary to prevent an unauthorized application from simply decrypting the encrypted key instead of importing it. However, because PKCS #11 wrapping mechanisms are insecure, all unwrapping keys have CKA_DECRYPT=true.

By default, keys that are unwrapped with a key that has CKA_DECRYPT permission are considered insecure. When the unwrap_kek parameter is set, the PKCS #11 API considers keys that are unwrapped with a key that also has CKA_DECRYPT permission as secure (provided there is no other reason to treat them as insecure).

By default, keys that have been derived by using CKM_DES3_ECB_ENCRYPT_DATA with a key that has CKA_ENCRYPT permission are considered insecure. However, when the derive_kek parameter is set, the PKCS #11 API considers keys that are derived with a key that has CKA_ENCRYPT permission as secure (provided that there is no other reason to treat them as insecure).

Normally, you can only use only extractable keys with CKM_XOR_BASE_AND_DATA and, on unextractable keys, only CKM_DES3_ECB_ENCRYPT_DATA is allowed by CKA_DERIVE. However, when the derive_xor parameter is set, the PKCS #11 API also allows such functions with keys that are not extractable and treats them as secure (provided that there is no other reason to treat them as insecure).

Normally, you can only use session keys with CKM_CONCATENATE_BASE_AND_KEY for use with the operation C_DeriveKey. However, when the derive_concatenate parameter is set, the PKCS #11 API also allows such functions with keys that are long term (token) keys. The PKCS #11 API treats these keys as secure, provided there is no other reason to treat them as insecure. Even if the all parameter is set, if you do not include the CKA_ALLOWED_MECHANISMS with CKM_CONCATENATE_BASE_AND_KEY, this C_DeriveKey operation will not be allowed.

The unwrap_rsa_aes_kwp parameter only applies to firmware version 13.3 or earlier. It is not needed in later versions.

The C_UnwrapKey operation with CKM_RSA_AES_KEY_WRAP imports the temporary AES key with an nCore API ACL that permits unwrapping of the wrapped target key by the temporary AES key. When using the C_UnwrapKey operation with only a user supplied template (pTemplate) it is possible to create this ACL such that it permits a one-time unwrap of only the wrapped target key. When the RSA unwrapping key has CKA_UNWRAP_TEMPLATE set it is necessary to construct the ACL when the RSA key is created in order to setup the partitioning guarantees from the CKA_UNWRAP_TEMPLATE. The intended wrapped target keys are unknown at this time, which means the ACL must permit a one-time unwrap of any key.

The Security Assurance Mechanism (SAM) considers this scenario insecure by default and therefore the use of the C_UnwrapKey operation with CKM_RSA_AES_KEY_WRAP is disabled when the RSA unwrapping key has CKA_UNWRAP_TEMPLATE set. When the unwrap_rsa_aes_kwp parameter is set the SAM enables the C_UnwrapKey operation with CKM_RSA_AES_KEY_WRAP in this scenario. The RSA unwrapping key must also explicitly allow the CKM_RSA_AES_KEY_WRAP mechanism via CKA_ALLOWED_MECHANISMS in addition to setting the unwrap_rsa_aes_kwp (or all) parameter; otherwise, the C_UnwrapKey operation will remain disabled when the RSA unwrapping key has CKA_UNWRAP_TEMPLATE set.

The weak_<algorithm> parameter allows you to treat keys used with a weak algorithm as secure. For example, DES is not secure, but setting the parameter weak_des means that such keys are considered secure. You can apply the weak_<algorithm> parameter to all keys that have a short fixed key length or whose algorithms have other security problems. As a guide, weak algorithms are those whose work factor to break is less than approximately 80 bits.

The shortkey_<algorithm=bitlength> parameter permits excessively short keys for the specified <algorithm> to be treated as secure. The parameter <bitlength> specifies the minimum length, in bits, that is to be considered secure. For example, RSA keys must usually be at least 1024 bits long in order to be treated as secure, but shortkey_rsa=768 would allow 768-bit RSA keys to be treated as secure.

The silent parameter turns off the warning output. Checks are still performed and still return failures correctly according to the other variables that are set.

When the CKNFAST_OVERRIDE_SECURITY_ASSURANCES environment variable is set to a value other than all, diagnostic messages are always generated for questionable operations. Each message contains the following elements:

If the problem is not that a questionable operation has been permitted because of a setting in CKNFAST_OVERRIDE_SECURITY_ASSURANCES it could be that an operation has failed. In such a case, the setting required to authorize the operation is noted.

By default, these messages are sent to stderr. On Windows platforms, they are also always sent to the Event Viewer. If a file name has been specified in the CKNFAST_ASSURANCE_LOG environment variable, diagnostic messages are also written to this file.

If CKNFAST_DEBUG is 1 or greater and a file is specified in CKNFAST_DEBUGFILE, the PCKS #11 library Security Assurance Mechanism log information is sent to the specified file. These variables must be set whenever generatekey or KeySafe are used.