Application interfaces

After installation, you can test that the nCipherKM JCA/JCE CSP is functioning correctly by running the command.

For Java 8:

For Java 11 and Java 17:

If the nCipherKM JCA/JCE CSP is functioning correctly, output from this command has the following form:

If the nCipherKM provider is installed but is not registered at the top of the providers list in the java.security file, the InstallationTest command produces output that includes the message:

In such a case, edit the java.security file (located in the security directory for your local JVM installation) so that the nCipherKM provider is registered in the first position in that file’s list of providers. For more information about the java.security file, see Installing the nCipherKM JCA/JCE CSP.

If the nCipherKM provider is not installed at all, or you have not created a Security World, or if you have not configured ports correctly in the hardserver configuration file, the InstallationTest command produces output that includes the message:

In such case:

After making any changes to the nCipherKM JCA/JCE CSP installation, run the InstallationTest command again and check the output.

Whether or not the nCipherKM provider is correctly installed, if the unlimited strength jurisdiction files are not installed or (not correctly installed), the InstallationTest command produces output that includes the message:

This message means that, because the Java Virtual Machine imposes limits on the cryptographic strength that you can use by default with JCE providers, you must replace the default policy configuration files with the unlimited strength policy files. For information about how to install the unlimited strength jurisdiction files, see Installing the nCipherKM JCA/JCE CSP.

The JCECSP_DEBUG system property is a bit mask for which you can set different values to control the debugging functions. The following table describes the effects of different values that you can set for this property:

To set multiple logging functions, add up the JCECSP_DEBUG values for the debugging functions you want to set, and specify the total as the value for JCECSP_DEBUG. For example, if you want to set the debugging to use both function tracing (bit 4) and function tracing with parameters (bit 5), add the JCECSP_DEBUG values shown in the table for these debugging functions (8 + 16 = 24) and specify this total (24) as the value to use for JCECSP_DEBUG.

The nShield HSM includes a hardware random number generator. A hardware random number generator provides greater security than the pseudo-random number generators provided by host computers. Therefore, always use the nShield HSM to generate random numbers and keys.

The nShield PKCS #11 library can use the nShield HSM to sign and verify messages using the following algorithms:

An nShield hardware security module is specifically optimized for public key algorithms, and therefore it will provide significant acceleration for DSA, RSA and ECDSA signature generation and verification. You should always choose to perform asymmetric signature generation and verification with an nShield HSM.

The nShield PKCS #11 library can use an nShield HSM to perform asymmetric encryption and decryption with the RSA algorithm.

The nShield HSM is specifically optimized for asymmetric algorithms, so you should always choose to perform asymmetric operations with the nShield HSM.

The nShield PKCS #11 library can use the nShield HSM to perform symmetric encryption with the following algorithms:

Because of limitations on throughput, these operations can be slower on the nShield HSM than on the host computer. However, although the nShield HSM may be slower than the host under a light load, you may find that under a heavy load the advantage gained from off-loading the symmetric cryptography (which frees the host CPU for other tasks) means that you achieve better overall performance.

The nShield PKCS #11 library can perform message digest operations with MD5, SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512 algorithms. However, for reasons of throughput, the library performs these operations on the host computer.

The mechanisms currently supported by the nShield PKCS #11 library, including some vendor-supplied mechanisms, are listed in the Cryptographic API Integration Guide.

The nShield PKCS #11 library can use an nShield HSM to wrap (encrypt) a private or secret key, or to unwrap (decrypt) a wrapped key.

The mechanisms supported by the nShield PKCS #11 library, including some vendor-supplied mechanisms, are listed in the Cryptographic API Integration Guide.

Questionable operations largely relate to the concept of a key being secure. A private or secret key is considered insecure if there is some reason for believing that its value may be available outside the HSM. Public keys are never considered insecure; by definition they are intended to be public.

An explicitly insecure PKCS #11 key is one where CKA_SENSITIVE is set to false. If an application uses a key that is insecure but CKA_SENSITIVE is not set to false, it is possible that the application is using an inadequate concept of key security, and that the library disallows use of that key by default. Use of insecure keys should, by default, be restricted to short-term session keys, and applications should explicitly recognize the insecurity.

If load-sharing mode is enabled, the nShield PKCS #11 library creates a virtual slot for each OCS in the Security World (returning the name of the card set) unless you have set CKNFAST_CARDSET_HASH (as described in CKNFAST_CARDSET_HASH).

An additional virtual slot may be returned (with the label of accelerator), depending on the value given to the variable CKNFAST_NO_ACCELERATOR_SLOTS (described in CKNFAST_NO_ACCELERATOR_SLOTS). Accelerator slots can:

When you insert a smart card from an OCS in the current Security World, the nShield PKCS #11 library treats this card as a PKCS #11 token that is present in the virtual slot for that OCS.

After the PKCS #11 token is present, you can open a session to that token. Until you log in, a session can only access public objects that belong to that PKCS #11 token.

The PKCS #11 token is present until you remove the last card belonging to the OCS. When you remove the token, the nShield PKCS #11 library closes any open sessions.

Logging in gives access to the private objects that are protected by the PKCS #11 token. Logging in requires the passphrase for the OCS. The exact mechanism for supplying the passphrase depends on the application that you are running.

The PKCS #11 token is shared across all the HSMs that have a smart card from the OCS in the reader at the point that you log in. After you have logged in, inserting additional cards from this OCS has no effect.

If you remove a smart card that belongs to a logged-in token, the nShield PKCS #11 library closes any open sessions and marks the token as being not present (unless the OCS is persistent). Removing a card from a persistent OCS has no effect, and the PKCS #11 token remains present until you log out.

If HSM Pool mode is enabled, the nShield PKCS #11 library exposes a single pool of HSMs and a single virtual slot for a fixed token with the label accelerator. This accelerator slot can be used to create module protected keys and to support session objects. HSM Pool mode does not support token protected keys, any pre-existing OCS or softcard protected keys are hidden from PKCS #11. In FIPS 140 Level 3 Security Worlds, keys cannot be created in HSM Pool mode, however keys created outside HSM Pool mode, for example using generatekey or a non-Pool mode PKCS #11 application, can be used in HSM Pool mode.

There will be two entries for each HSM, unless you have set CKNFAST_NO_ACCELERATOR_SLOTS.

Use the second of the two entries (which has the same name as the Operator Card that is currently in a smart card reader) to protect your keys or token objects.

PKCS #11 does not allow two tokens to be present in the same slot. Therefore, when you insert a smart card into a reader, the nShield PKCS #11 library logs out any previously logged-in token from the slot and closes any open sessions.

You can use the preload command-line utility to preload K/N OCSs before actually using PKCS #11 applications. The preload utility loads the logical token and then passes it to the PKCS #11 utilities.

You must provide any required passphrase for the tokens when using preload to load the card set. However, because the application is not aware that the card set has been preloaded, the application operates normally when handling the login activity (including prompting for a passphrase), but the PKCS  #11 library will not actually check the supplied passphrase. preload must be also used with the cksotool utility to perform operations that require the PKCS #11 Security Officer role.

Normally, preload uses environment variables to pass information to the program using the preloaded objects, including the PKCS #11 library. Therefore, if the application you are using is one that clears its environment before the PKCS #11 library is loaded, you must set the appropriate values in the cknfastrc file (see nShield PKCS #11 library environment variables). The current environment variables remain usable. The default setting for the CKNFAST_LOADSHARING environment variable changes from specifying load-sharing as disabled to specifying load-sharing as enabled. Moreover, in load-sharing mode, the loaded card set is used to set the environment variable CKNFAST_CARDSET_HASH so that only the loaded card set is visible as a slot.

The NFAST_NFKM_TOKENSFILE environment variable must also be set in the cknfastrc file to the location of the preload file (see Environment variables).

A logical token preloaded by preload for use with the nShield PKCS #11 library is the only such token available to the application for the complete invocation of the library. You can use more than one HSM with the same card set.

If the loaded card set is non-persistent, then a card must be left in each HSM on which the set has been loaded during the start-up sequence. After a non-persistent card has been removed, the token is not present even if the card is reinserted.

If load-sharing has been specifically switched off, you see multiple slots with the same label.

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.

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

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 nfkminfo: information utility.

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

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.

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.

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

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.

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.

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.

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.

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.

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.

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

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.

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

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.

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:

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

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

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

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

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.

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

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.

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

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.

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.

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

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

Set this variable to enable PKCS #11 key reloading. See section PKCS _11 with key reloading in the Cryptographic API Integration Guide.

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

In addition, the Enhanced SChannel Cryptographic Provider and the Enhanced DSS and Diffie-Hellman SChannel Cryptographic Provider support all the internal algorithm types necessary for SSL3 and TLS1 support.

The nShield CSPs do not support SSL2.

You can register the nShield CNG CSP with:

To register the nShield CNG CSP, the hardserver must be running and able to communicate with at least one module. This requirement is normally fulfilled during the product installation process. You can check that this requirement is fulfilled by running the enquiry command-line utility and checking the output for details about the module. See the Installation Guide for more information.

You can use the cngregister command-line utility to unregister or reregister the nShield CNG CSP manually.

To unregister the nShield CNG CSP, run the command:

This command unregisters the CNG CSP, but does not remove the provider DLL files from your system. For information about removing these files, see Uninstalling or reinstalling the CNG CSP.

After unregistering the nShield CNG CSP, you can reregister it at any time as long as the files have not been uninstalled from your system. To reregister the nShield CNG CSP on your system, run the command:

For more information about these command-line utilities, see Utilities for CNG.

To uninstall the nShield CNG CSP:

To reinstall the nShield CNG CSP after you have previously uninstalled it:

For more information about these command-line utilities, see Utilities for CNG

To import a Microsoft CAPI key into the Security World Key Storage Provider, first run the CAPI utility csputils to identify the existing CAPI containers and their key contents.

CAPI containers can contain either a signing key or a key exchange key, or both. The following example shows how to import both a signing key and a key exchange key from a Microsoft CAPI container:

To check the success of the import, list the keys present in the Security World Key Storage Provider:

The following example command shows how to import a single signing key:

Run the cnglist command with the --list-keys option to check the success of the key import:

To import a Microsoft CNG key into the Security World Key Storage Provider, run the cngimport command as shown in the following example:

Run the cnglist command with the --list-keys option to check the success of the key import:

The original key is not deleted from the provider from which it was imported:

To import a Security World key into the Security World Key Storage Provider, run the cngimport utility as shown in the following example:

Run cnglist with the --list-keys option to confirm that the key has been successfully imported:

To import an nShield CAPI container into the Security World Key Storage Provider, run the csputils command to identify the container name:

Identify the Security World key names of the keys in the container by running the csputils command as follows:

The key name to pass to the cngimport command --key option is the part of the key name that follows key_mscapi_ in the output line that starts Filename for signature key is key_mscapi_.

For example, the signature key file name for CAPICONTAINER in the example shown above is key_mscapi_ce51a0ee0ea164b993d1edcbf639f2be62c53222, so ce51a0ee0ea164b993d1edcbf639f2be62c53222 is the key name that should be passed to cngimport:

Run cnglist with the --list-keys option to confirm that the key has been successfully imported:

Follow the same procedure for importing the key exchange key from the nShield CAPI container.

Use cngimport to migrate keys to the Security World Key Storage Provider. For more information, see Migrating keys for CNG.

The cnginstall utility is used by the Security World Software installation wizard. You can also use this utility to manually uninstall (or reinstall) the nShield CNG DLLs and registry entries.

To uninstall the nShield CNG DLL files, run the command:

This command removes the provider DLL files from your system. It produces output of the form:

Before you uninstall the nShield CNG DLL files, ensure that you unregister the CNG CSP. For more information, see:

After unregistering the nShield CNG CSP, you can reregister it at any time as long as the files have not been uninstallted from your system. To reregister the nShield CNG CSP on your system, run the command:

For more information about uninstalling and reinstalling the nShield CNG CSP with cnginstall, see Uninstalling or reinstalling the CNG CSP.

Use cngregister to unregister the nShield CNG CSP manually.

To unregister the nShield CNG CSP, run the command:

This command produces output for the form:

This command unregisters the CNG CSP, but does not remove the provider DLL files from your system. For information about removing these files, see:

After unregistering the nShield CNG CSP, you can reregister it at any time as long as the files have not been uninstalled from your system. To reregister the nShield CNG CSP on your system, run the command:

Use cngsoak to obtain statistics about the performance of the nShield CNG CSP. Specifically, use cngsoak to determine the speed of:

The output from cngsoak displays information as columns of information. From left to right, these columns display:

Use the ncsvcdep utility to ensure that the nShield nFast Server service is running before certain services are enabled. For example, Active Directory Certificate Services or Internet Information Services require that the hardserver is running in order to use the nShield CNG CSP. Failure to set this dependency can lead to system instability.

To list installed services, run the ncsvcdep command with the -l option:

Output from this command has the form:

To set a dependency, run the command:

In this command, DependentService is the service that has the dependency. The following example shows how to make the Active Directory Certificate Services dependent on the nFast Server:

To remove a specific dependency relationship, run ncsvcdep with the -r option, for example:

To remove all dependencies, run ncsvcdep with the -x option:

Use cnglist to display details of CNG providers, keys, and algorithms.

To list details of the CNG providers, run the cnglist command with the --list-providers option:

Output from this command is of the form:

To list details of the algorithms, run the cnglist command with the --list-algorithms option:

Output from this command has the form:

To list details of the algorithms for the Security World Key Storage Provider, run the cnglist command with the --list-algorithms, --keystorage, and --nc options:

Output from this command has the form:

To list details of the algorithms for a specific named key storage provider, run the cnglist command with the --list-algorithms and --provider="ProviderName" options:

Output from this command has the form: