nShield PKCS #11 library environment variables

The nShield PKCS #11 library uses the following environment variables:

  • CKNFAST_ASSUME_SINGLE_PROCESS

  • CKNFAST_ASSURANCE_LOG

  • CKNFAST_CARDSET_HASH

  • CKNFAST_CONCATENATIONKDF_X963_COMPLIANCE

  • CKNFAST_DEBUG

  • CKNFAST_DEBUGDIR

  • CKNFAST_DEBUGFILE

  • CKNFAST_DH_LSB

  • CKNFAST_EDDSA_PUBKEY_FORMAT

  • CKNFAST_FAKE_ACCELERATOR_LOGIN

  • CKNFAST_HSM_POOL

  • CKNFAST_JCE_COMPATIBILITY

  • CKNFAST_LOADSHARING

  • CKNFAST_LOAD_KEYS

  • CKNFAST_NO_ACCELERATOR_SLOTS

  • CKNFAST_NO_SYMMETRIC

  • CKNFAST_NO_UNWRAP

  • CKNFAST_NONREMOVABLE

  • CKNFAST_NVRAM_KEY_STORAGE

  • CKNFAST_OVERRIDE_SECURITY_ASSURANCES

  • CKNFAST_RELOAD_KEYS

  • CKNFAST_SEED_MAC_ZERO

  • CKNFAST_SESSION_THREADSAFE

  • CKNFAST_SHARE_SESSION_KEYS

  • CKNFAST_TOKENS_PERSISTENT

  • CKNFAST_USE_THREAD_UPCALLS

  • CKNFAST_WRITE_PROTECTED

If you used the default values in the installation script, you should not need to change any of these environment variables.

You can set environment variables in the file cknfastrc.

Linux

This file must be in the /opt/nfast/ directory of the client.

Windows

If the NFAST_HOME environment variable is not set, or if environment variables are cleared by your application, the file cknfastrc must be in the %NFAST_HOME% directory of the client.

The cknfastrc file should be saved without any suffix (such as .txt).

Each line of the file cknfastrc must be of the following form:

<variable>=<value>
Variables set in the environment are used in preference to those set in the resource file.

Changing the values of these variables after you start your application has no effect until you restart the application.

If the description of a variable does not explicitly state what values you can set, the values you set are normally 1 or 0, Y or N.

For more information concerning Security World Software environment variables that are not specific to PKCS #11 and which are used to configure the behavior of your nShield installation, see the Security World Software installation instructions.

CKNFAST_ASSUME_SINGLE_PROCESS

By default, this variable is set to 1. This specifies that only token objects that are loaded at the time C_Initialize is called are visible.

Setting this variable to 0 means that token objects created in one process become visible in another process when it calls C_FindObjects. Existing objects are also checked for modification on disc; if the key file has been modified, then the key is reloaded. Calling C_SetAttributeValues or C_GetAttributeValues also checks whether the object to be changed has been modified in another process and reloads it to ensure the most recent copy is changed.

Setting the variable to 0 can slow the library down because of the additional checking needed if a large number of keys are being changed and a large number of existing objects must be reloaded.

CKNFAST_ASSURANCE_LOG

This variable is used to direct all warnings from the Security Assurance Mechanism to a specific log file.

CKNFAST_CARDSET_HASH

This variable enables you to specify a specific card set to be used in load-sharing mode. If this variable is set, only the virtual smart card slot that matches the specified hash is present (plus the accelerator slot). The hash that you use to identify the card set in CKNFAST_CARDSET_HASH is the SHA-1 hash of the secret on the card. Use the nfkminfo command-line utility to identify this hash for the card set that you want to use: it is listed as hkltu. For more information about using nfkminfo, see the User Guide for your HSM.

CKNFAST_CONCATENATIONKDF_X963_COMPLIANCE

Sets the correct use of ECDH derive with concatenate KDF using the ANSI X9.63 specification as per the PKCS#11 standard.

The default is ANSI X9.63 to match that of the PKCS #11 Specification.
ECDH derive with concatenate KDF SP800-56a can use the standard PKCS #11 v3 CKD_SHA[x]_SP800_KDF values.

CKNFAST_DEBUG

This variable is set to enable PKCS #11 debugging. The values you can set are in the range 0 - 11. If you are using NFLOG_* for debugging, you must set CKNFAST_DEBUG to 1.

Value Description

0

None (default setting)

1

Fatal error

2

General error

3

Fix-up error

4

Warnings

5

Application errors

6

Assumptions made by the nShield PKCS #11 library

7

API function calls

8

API return values

9

API function argument values

10

Details

11

Mutex locking detail

CKNFAST_DEBUGDIR

If this variable is set to the name of a writeable directory, log files are written to the specified directory. The name of each log file contains a process ID. This can make debugging easier for applications that fork a lot of child processes.

CKNFAST_DEBUGFILE

You can use this variable to write the output for CKNFAST_DEBUG (Path name > file name).

CKNFAST_DH_LSB

If this variable is set the least significant bytes of the result of DH/ECDH key agreement using the CKM_DH_PKCS_DERIVE, CKM_X9_42_DH_DERIVE or CKM_ECDH1_DERIVE mechanisms are taken. This is in line with the PKCS#11 specification. If this variable is not set the most significant bytes will be used. The latter behavior is consistent with Security World software prior to v12.81.

CKNFAST_EDDSA_PUBKEY_FORMAT

If applications require the CKA_EC_POINT output (C_GetAttributeValue) as an ASN.1 Bit String, set this variable to bits, otherwise it will be supplied as an ASN.1 Octet String.

This only applies to EDDSA keys.

CKNFAST_FAKE_ACCELERATOR_LOGIN

If this variable is set, the nShield PKCS #11 library accepts a PIN for a module-protected key, as required by Sun Java Enterprise System (JES), but then discards it. This means that a Sun JES user requesting a certificate protected by a load-shared HSM can enter an arbitrary PIN and obtain the certificate.

CKNFAST_FAKE_ACCELERATOR slots allow the creation of objects with CKA_PRIVATE=TRUE in the template even though the login is "fake" and the objects are not private.

  • Examining the attributes shows CKA_PRIVATE as FALSE.

  • A search for the object will not find it if the search criteria includes CKA_PRIVATE=TRUE.

CKNFAST_HSM_POOL

HSM Pool mode is determined by the state of the CKNFAST_HSM_POOL environment variable.

Set the environment variable to 1, y or Y to enable HSM Pool mode for the PKCS #11 application, or set to 0, n or N to explicitly disable HSM Pool mode for the PKCS #11 application.

HSM Pool mode takes precedence over load-sharing mode. HSM Pool mode only supports module protected keys so do not use CKNFAST_NO_ACCELERATOR_SLOTS to disable the accelerator slot.

CKNFAST_JCE_COMPATIBILITY

This property is included to allow the saving of objects when using Java PKCS#11 providers.

It is possible, using C_CopyObject, to change a key’s CKA_TOKEN value from CK_FALSE to CK_TRUE. This requires the CKNFAST_JCE_COMPATIBILITY environment variable to be set to 1. The original key’s CKA_TOKEN value will remain unchanged.

CKNFAST_LOADSHARING

Load-sharing mode is determined by the state of the CKNFAST_LOADSHARING environment variable.

To enable load-sharing mode, set the environment variable CKNFAST_LOADSHARING to a value that starts with something other than 0, n, or N and ensure that the CKNFAST_HSM_POOL environment variable is not set. The virtual slot behavior then operates.

To use softcards with PKCS #11, you must have CKNFAST_LOADSHARING set to a nonzero value. When using pre-loaded softcards or other objects, the PKCS #11 library automatically sets CKNFAST_LOADSHARING=1 (load-sharing mode on) unless it has been explicitly set to 0 (load-sharing mode off).

CKNFAST_NO_ACCELERATOR_SLOTS

If this variable is set, the nShield PKCS #11 library does not create the accelerator slot, and thus the library only presents the smart card slots (real or virtual, depending on whether load-sharing is in use).

Do not set this environment variable if you want to use the accelerator slot to create or load module-protected keys.

Setting this environment variable has no effect on ckcheckinst because ckcheckinst needs to list accelerator slots.

CKNFAST_NO_SYMMETRIC

If this variable is set, the nShield PKCS #11 library does not advertise any symmetric key operations.

CKNFAST_NO_UNWRAP

If this variable is set, the nShield PKCS #11 library does not advertise the c_wrap and c_unwrap commands. You should set this variable if you are using Sun Java Enterprise System (JES) or Netscape Certificate Management Server as it ensures that a standard SSL handshake is carried out. If this variable is not set, Sun JES or Netscape Certificate Management Server make extra calls, which reduces the speed of the library.

CKNFAST_NONREMOVABLE

When this environment variable is set, the state changes of the inserted card set are ignored by the nShield PKCS  #11 library.

Since protection by non-persistent cards is enforced by the HSM, not the library, this variable does not make it possible to use keys after a non-persistent card is removed, or after a timeout expires.

CKNFAST_NVRAM_KEY_STORAGE

When this environment variable is set, the PKCS #11 library generates only keys in nonvolatile memory (NVRAM). You must also ensure this environment variable is set in order to delete NVRAM-stored keys.

CKNFAST_OVERRIDE_SECURITY_ASSURANCES

This variable can be assigned one or more of the following parameters, with an associated value where appropriate, to override the specified security assurances in key operations where this is deemed acceptable:

  • all

  • none

  • tokenkeys

  • longterm [=<days>]

  • explicitness

  • import

  • wrapping_crypt

  • unwrap_kek

  • derive_kek

  • derive_xor

  • derive_concatenate

  • unwrap_rsa_aes_kwp

  • weak_<algorithm>

  • shortkey_<algorithm>=<bitlength>

  • silent.

Each parameter specified is separated by a semicolon. Using the command line, enter the following to set the variable:

Linux
CKNFAST_OVERRIDE_SECURITY_ASSURANCES="<parameter1>;<parameter2>=<value3>"
Windows
set CKNFAST_OVERRIDE_SECURITY_ASSURANCES=<parameter1>;<parameter2>=<value3>

In the configuration file, enter the following to set the variable:

CKNFAST_OVERRIDE_SECURITY_ASSURANCES=<parameter1>;<parameter2>=<value3>

Unknown parameters generate a warning; see Diagnostic warnings about questionable operations.

The meaning of these parameters is described in the rest of this section.

all

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.

none

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.

tokenkeys

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.

longterm[=days]

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.

A need to set this variable usually means that some important keys that should be protected by the HSM’s security are not secure.

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:

  • C_Sign and C_SignUpdate

  • C_Verify and C_VerifyUpdate

  • C_Encrypt and C_EncryptUpdate

  • C_Decrypt and C_DecryptUpdate.

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.

explicitness

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.

A need to set the explicitness parameter does not necessarily indicate a problem, but does usually indicate that a review of the application’s security policies and use of the PKCS #11 API should be carried out.

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.

import

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.

Setting this variable at any other time indicates that the library regards the key as secure, even though it is not always kept within a secure environment.

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.

wrapping_crypt

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.

unwrap_kek

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

derive_kek

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

derive_xor

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

derive_concatenate

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.

unwrap_rsa_aes_kwp

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.

weak_<algorithm>

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.

shortkey_<algorithm=bitlength>

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.

silent

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.

Diagnostic warnings about questionable operations

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:

  • The PKCS #11 label of the key, if available

  • The PKCS #11 identifier of the key, if available

  • The hash of the key

  • A summary of the problem.

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.

If a file is specified in CKNFAST_ASSURANCES_LOG and no file is specified in CKNFAST_DEBUGFILE (or if CKNFAST_DEBUG is 0), diagnostic messages are sent to stderr as well as to the file specified in CKNFAST_ASSURANCES_LOG.

CKNFAST_SEED_MAC_ZERO

Set this variable to use zero padding for the Korean SEED MAC mechanisms (CK_SEED_MAC and CKM_SEED_MAC_GENERAL). If this variable is not set, or is set to n, then the SEED MAC mechanisms will use the default PKCS #5 padding scheme.

CKNFAST_SESSION_THREADSAFE

You must set this environment variable to yes if you are using the Sun PKCS #11 provider when running nCipherKM JCA/JCE code.

CKNFAST_SHARE_SESSION_KEYS

This variable can take a list of one or more semi-colon (;) separated values to improve performance through loadsharing when session keys are used. See CKNFAST_LOADSHARING.

Loadsharing improves performance and adds resilience in the case of module failure. However, if the key is used only a few times, the overhead of sharing it may be greater than the performance benefit. If a key will be used many times or if it has a long lifespan, sharing is recommended.

  • all (default)

  • copy

  • derive

  • generate

  • import

  • none

  • unwrap

If the origin of the session key matches a selected category, then the key is automatically shared to all HSMs when it is created.

CKNFAST_TOKENS_PERSISTENT

This variable controls whether or not the Operator Cards that are created by your PKCS #11 application are persistent. If this variable is set when your application calls the PKCS #11 function that creates tokens, the Operator Card created is persistent.

Use of the nShield PKCS #11 library to create tokens is deprecated, because it can only create 1/1 tokens in FIPS 140 Level 2 Security Worlds. Use KeySafe or one of the command-line utilities to create OCSs.

CKNFAST_USE_THREAD_UPCALLS

If this variable is set and CKF_OS_LOCKING_OK is passed to C_Initialize, NFastApp_SetThreadUpcalls is called by means of nfast_usencthreads and only a single NFastApp_Connection is used, shared between all threads.

If this variable is set and mutex callbacks are passed to C_Initialize but CKF_OS_LOCKING_OK is not passed, C_Initialize fails with CKR_FUNCTION_FAILED. (NFastApp_SetThreadUpcalls requires more callbacks than just the mutex ones that PKCS #11 supports.)

If neither mutex callbacks nor CKF_OS_LOCKING_OK is passed, this variable is ignored. Only a single connection is used because the application must be single threaded in this case.

CKNFAST_LOAD_KEYS

This variable will load private objects at C_Login time, rather than at the first cryptographic operation.

CKNFAST_WRITE_PROTECTED

Set this variable to make your OCS or softcard (token) write-protected. If a token is write-protected, you cannot:

  • Generate certificate, data, and key objects for that token.

  • Modify attributes of an existing object.

This environment variable does not prevent you from deleting an object from your token.

CKNFAST_RELOAD_KEYS

Set this variable to enable PKCS #11 key reloading. See PKCS#11 with key reloading.

Key reloading requires load sharing-mode to operate, and enables it automatically if CKNFAST_LOADSHARING is not set.