Application interfaces

This chapter explains how to use an HSM with various types of application:

  • nCipherKM JCA/JCE CSP

  • PKCS #11 applications

  • nShield native and Custom applications

  • CodeSafe applications

  • Microsoft CAPI CSP

  • Microsoft CNG CSP.

For information about using the Microsoft Cryptographic API, see the appropriate third-party integration guide at: https://www.entrust.com/documentation.

You can use KeySafe or the generatekey utility to generate or import keys for use with your applications (see Working with keys). By default, KeySafe uses the same mechanisms and supports the same applications as the generatekey utility.

By default, any user is allowed to use any application that uses an nShield HSM.
If you create keys on a client that is not on the same computer as the RFS, you must copy the key data to the RFS before the nShield HSM can use these keys.

nCipherKM JCA/JCE CSP

The nCipherKM JCA/JCE CSP (Cryptographic Service Provider) allows Java applications and services to access the secure cryptographic operations and key management provided by Entrust hardware. This provider is used with the standard JCE (Java Cryptographic Extension) programming interface.

To use the nCipherKM JCA/JCE CSP, you must install:

  • the nShield Java package which includes the nShield Java jars and KeySafe.

For more information about the bundles and components supplied on your Security World Software installation media, see the User Guide.

The following versions of Java have been tested to work with, and are supported by, your nShield Security World Software:

  • Java 7 (or Java 1.7x)

  • Java 8 (or Java 1.8x).

  • Java 11

We recommend that you ensure Java is installed before you install the Security World Software. The Java executable must be on your system path.

If you can do so, please use the latest Java version currently supported by Entrust that is compatible with your requirements. Java versions before those shown are no longer supported. If you are maintaining older Java versions for legacy reasons, and need compatibility with current nShield software, please contact Entrust nShield Technical Support, https://nshieldsupport.entrust.com.

To install Java you may need installation packages specific to your operating system, which may depend on other pre-installed packages to be able to work.

Suggested links from which you may download Java software as appropriate for your operating system:

Detailed documentation for the JCE interface can be found on the Oracle Technology web page https://docs.oracle.com/en/java/javase/11/security/java-cryptography-architecture-jca-reference-guide.html.
Softcards are not supported for use with the nCipherKM JCA/JCE CSP in Security Worlds that are compliant with FIPS 140-2 Level 3.

Installing the nCipherKM JCA/JCE CSP

To install the nCipherKM JCA/JCE CSP:

  1. In the hardserver configuration file, ensure that:

    • priv_port (the port on which the hardserver listens for local privileged TCP connections) is set to 9001

    • nonpriv_port (the port on which the hardserver listens for local nonprivileged TCP connections) is set to 9000.

      If you need to change either or both of these port settings, you restart the hardserver before continuing the nCipherKM JCA/JCE CSP installation process. For more information, see Stopping and restarting the hardserver.

  2. For Java 7 and 8 only. Copy the nCipherKM.jar file to the extensions folder of your local Java Virtual Machine installation from the following directory:

    • %NFAST_HOME%\java\classes

      The location of the extensions folder depends on the type of your local Java Virtual Machine (JVM) installation:

      JVM type Extensions folder

      Java Developer Kit (JDK)

      %JAVA_HOME%\jre\lib\ext

      Java Runtime Environment (JRE)

      %JAVA_HOME%\lib\ext

    In these paths, %JAVA_HOME% is the home directory of the Java installation (commonly specified in the JAVA_HOME environment variable). If you are using Java 11 you do not need to copy the jar file.

  3. Add %JAVA_HOME%\bin to your PATH system variable

  4. For Java 7 and 8 only. Install the unlimited strength JCE jurisdiction policy files that are appropriate to your version of Java. JDK 9 and later ship with, and use by default, the unlimited policy files.

    The Java Virtual Machine imposes limits on the cryptographic strength that may be used by default with JCE providers. Replace the default policy configuration files with the unlimited strength policy files.

    To install the unlimited strength JCE jurisdiction policy files:

    1. If necessary, download the archive containing the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files from the Web site of your Java Virtual Machine vendor.

      The Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files are covered and controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. We recommend that you take legal advice before downloading these files from your Java Virtual Machine vendor.

    2. Extract the files local_policy.jar and US_export_policy.jar from Java Virtual Machine vendor’s Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy File archive.

    3. Copy the extracted files local_policy.jar and US_export_policy.jar into the security directory for your local Java Virtual Machine (JVM) installation:

      JVM type Extensions folder

      Java Developer Kit (JDK)

      %JAVA_HOME%\jre\lib\security

      Java Runtime Environment (JRE)

      %JAVA_HOME%\lib\security

      In these paths, %JAVA_HOME% is the home directory of the Java installation (commonly specified in the JAVA_HOME environment variable).

      Copying the files local_policy.jar and US_export_policy.jar into the appropriate folder must overwrite any existing files with the same names.

  5. Add the nCipherKM provider to the Java security configuration file java.security (located in the security directory for your local Java Virtual Machine (JVM) installation).

    The java.security file contains a list of providers in preference order that is used by the Java Virtual Machine to decide from which provider to request a mechanism instance. Ensure that the nCipherKM provider is registered in the first position in this list, as shown in the following example:

    #
# List of providers and their preference orders (see above):
#
security.provider.1=com.ncipher.provider.km.nCipherKM
security.provider.2=sun.security.provider.Sun
security.provider.3=sun.security.rsa.SunRsaSign
security.provider.4=com.sun.net.ssl.internal.ssl.Provider
security.provider.5=com.sun.crypto.provider.SunJCE
security.provider.6=sun.security.jgss.SunProvider
security.provider.7=com.sun.security.sasl.Provider

    For Java 11 you do not need to specify the fully qualified class name for the provider. Instead you can just use the provider name.

    security.provider.1=nCipherKM

    Placing the nCipherKM provider first in the list permits the nCipherKM provider’s algorithms to override the algorithms that would be implemented by any other providers (except in cases where you explicitly request another provider name).

    The nCipherKM provider cannot serve requests required for the SSL classes unless it is in the first position in the list of providers.

    Do not change the relative order of the other providers in the list.

    If you add the nCipherKM provider as security.provider.1, ensure that the subsequent providers are re-numbered correctly. Ensure you do not list multiple providers with the same number (for example, ensure your list of providers does not include two instances of security.provider.1, both com.ncipher.provider.km.nCipherKM and another provider).

  6. Save your updates to the file java.security.

    When you have installed the nCipherKM JCA/JCE CSP, you must have created a Security World before you can test or use it. For more information about creating a Security World, see Creating a Security World.

    If you have a Java Enterprise Edition Application Server running, you must restart it before the installed nCipherKM provider is loaded into the Application Server virtual machine and ready for use.

Testing the nCipherKM JCA/JCE CSP installation

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

For Java 7 and Java 8:

java com.ncipher.provider.InstallationTest

For Java 11:

java --module-path %NFAST_HOME%\java\classes com.ncipher.provider.InstallationTest
For this command to work, you must have added %JAVA_HOME% to your PATH system variable).

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

Installed providers:
1: nCipherKM
2: SUN
3: SunRsaSign
4: SunJSSE
5: SunJCE
6: SunJGSS
7: SunSASL
Unlimited strength jurisdiction files are installed.
The nCipher provider is correctly installed.
nCipher JCE services:
Alg.Alias.Cipher.1.2.840.113549.1.1.1
Alg.Alias.Cipher.1.2.840.113549.3.4
Alg.Alias.Cipher.AES
Alg.Alias.Cipher.DES3

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:

The nCipher provider is installed, but is not registered at the top of the providers list in the java.security file.
See the user guide for more information about the recommended system configuration.

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:

The nCipher provider is not correctly installed.

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:

Unlimited strength jurisdiction files are NOT installed.

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.

Named Modules in Java 11

The nCipherKM Provider has been implemented as a named module. This means that, for Java 11, if you have added the provider to your java.security file, then you can run your application with the nCipherKM.jar on the module-path and the Java ServiceLoader class will automatically find it, e.g.

java --module-path %NFAST_HOME%\java\classes com.ncipher.provider.InstallationTest

Alternatively, you can specify the location of the nCipherKM jar on the classpath:

java --class-path %NFAST_HOME%\java\classes\nCipherKM.jar com.ncipher.provider.InstallationTest

keytool

You can use either the Oracle keytool utility or the IBM keytool utility to read and edit an nShield KeyStore. These utilities are shipped with the Oracle and IBM JVMs. You must specify the correct nCipher.sworld KeyStore type when you run the keytool utility, and you must specify the correct package name for the Oracle or IBM keytool utility.

To generate a new key in an OCS-protected KeyStore with the Oracle or IBM keytool utility, run the appropriate command:

  • Sun Microsystems keytool utility:

    For Java 11, use the following command:

    java --module-path /opt/nfast/java/classes sun.security.tools.keytool.Main -genkey -storetype nCipher.sworld -keyalg RSA -sigalg SHA1withRSA -storepass <KeyStore_passphrase> -keystore <KeyStore_path>

    For Java 8, use the following command:

    java sun.security.tools.keytool.Main -genkey -storetype nCipher.sworld -keyalg RSA -sigalg SHA1withRSA -storepass <KeyStore_passphrase> -keystore <KeyStore_path>

    For Java 7, use the following command:

    java sun.security.tools.KeyTool -genkey -storetype nCipher.sworld -keyalg RSA -sigalg SHA1withRSA -storepass <KeyStore_passphrase> -keystore <KeyStore_path>

  • IBM keytool utility:

    java com.ibm.crypto.tools.KeyTool -genkey -storetype nCipher.sworld -keyalg RSA -sigalg SHA1withRSA -storepass <KeyStore_passphrase> -keystore <KeyStore_path>

In these example commands, <KeyStore_passphrase> is the passphrase for the OCS that protects the KeyStore and <KeyStore_path> is the path to that KeyStore.

To generate a new key in a module-protected KeyStore with the Oracle or IBM keytool utility, run the appropriate command:

  • Sun Microsystems keytool utility:

    For Java 11, use the following command:

    java --module-path /opt/nfast/java/classes -Dprotect=module -DignorePassphrase=true sun.security.tools.keytool.Main -genkey -storetype nCipher.sworld -keyalg RSA -sigalg SHA1withRSA -keystore <KeyStore_path>

    For Java 8, use the following command:

    java -Dprotect=module -DignorePassphrase=true sun.security.tools.keytool.Main -genkey -storetype nCipher.sworld -keyalg RSA -sigalg SHA1withRSA -keystore <KeyStore_path>

    For Java 7, use the following command:

    java -Dprotect=module -DignorePassphrase=true sun.security.tools.KeyTool -genkey -storetype nCipher.sworld -keyalg RSA -sigalg SHA1withRSA -keystore <KeyStore_path>

  • IBM keytool utility:

    * java -Dprotect=module -DignorePassphrase=true com.ibm.crypto.tools.KeyTool -genkey -storetype nCipher.sworld -keyalg RSA -sigalg SHA1withRSA -keystore <KeyStore_path>

In these example commands, <KeyStore_path> is the path to the KeyStore.

By default, the keytool utilities use the MD5withRSA signature algorithm to sign certificates used with a KeyStore. This signature mechanism is unavailable on modules with firmware version 2.33.60 or later.

Using keys

Only the nCipherKM provider can use keys stored in an nShield KeyStore because the underlying key material is held separately in the Security World.

You can always store nShield keys in an nShield KeyStore. You can also store keys generated by a third-party provider into an nShield KeyStore if both of the following conditions apply:

  • the key type is known to the nCipherKM provider

  • the Security World is not compliant with FIPS 140-2 Level 3.

When you generate an nShield key (or create it from imported key material), that key is associated with an ACL (Access Control List). This ACL prevents the key from being used for operations for which it is unsuited and enforces requirements that certain tokens be presented; for example, the ACL can specify that signing key cannot be used for encryption.

System properties

You can use system properties to control the provider. You set system properties when starting the Java Virtual Machine using a command such as:

java -D<property>=<value> <MyJavaApplication>

In this example command, <property> represents any system property, <value> represents the value set for that property, and <MyJavaApplication> is the name of the Java application you are starting. You can set multiple system properties in a single command, for example:

java -Dprotect=module -Dignorepass phrase=true <MyJavaApplication>

The available system properties and their functions as controlled by setting different values for a property are described in the following table:

Property Function for different values

JCECSP_DEBUG

This property is a bit mask for which different values specify different debugging functions; the default value is 0. For details about the effects of setting different values for this property, see JCECSP_DEBUG property values.

JCECSP_DEBUGFILE

This property specifies a path to the file to which logging output is to be written. Set this property if the JCECSP_DEBUG property is set to a value other than the default of 0. For details about the effects of setting different values for this property, see JCECSP_DEBUG property values.

In a production environment, we recommend that you disable debug logging to prevent sensitive information being made available to an attacker.

protect

This property specifies the type of protection to be used for key generation and nCipherKM KeyStore instances. You can set the value of this property to one of module, <SOFTCARD_NAME:SOFTCARD_IDENT>, or cardset. OCS protection (cardset) uses the card from the first slot of the first usable hardware security module. To find the logical token hash <IDENT> of a softcard, run the command nfkminfo ‑‑softcard‑list.

module

This property lets you override the default HSM and select a specific HSM to use for HSM and OCS protection. Set the value of this property as the ESN of the HSM you want to use.

slot

This property lets you override the default slot for OCS-protection and select a specific slot to use. Set this the value of this property as the number of the slot you want to use.

ignorepass phrase

If the value of this property is set to true, the nCipherKM provider ignores the pass phrase provided in its KeyStore implementation. This feature is included to allow the Oracle or IBM keytool utilities to be used with module-protected keys. The keytool utilities require a pass phrase be provided; setting this property allows a dummy pass phrase to be used.

seeintegname

Setting the value of this property to the name of an SEE integrity key causes the provider to generate SEE application keys. These keys may only be used by an SEE application signed with the named key.

com.ncipher.provider.announcemode

The default value for this property is auto, which uses firmware auto-detection to disable algorithms in the provider that cannot be supported across all installed HSMs. Setting the value of this property to on forces the provider to advertise all mechanisms at start-up. Setting the value of this property to off forces the provider to advertise no mechanisms at start-up.

com.ncipher.provider.enable

For the value of this property, you supply a comma-separated list of mechanism names that are to be forced on, regardless of the announce mode selected.

com.ncipher.provider.disable

For the value of this property, you supply a comma-separated list of mechanism names that are to be forced off, regardless of the announce mode selected. Any mechanism supplied in the value for the com.ncipher.provider.disable property overrides the same mechanism if it is supplied in the value for the com.ncipher.provider.enable property.

JCECSP_DEBUG property values

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:

JCECSP_DEBUG value Function

0

If this property has no bits set, no debugging information is reported. This is the default setting.

1

If this property has the bit 1 set, minimal debugging information (for example, version information and critical errors) is reported.

2

If this property has the bit 2 set, comprehensive debugging information is reported.

4

If this property has the bit 3 set, debugging information relating to creation and destruction of memory and HSM resources is reported.

8

If this property has the bit 4 set, debugFunc and debugFuncEnd generate debugging information for functions that call them.

16

If this property has the bit 5 set, debugFunc and debugFuncEnd display the values for all the arguments that are passed in to them.

32

If this property has the bit 6 set, context information is reported with each debugging message (for example, the ThreadID and the current time.

64

If this property has the bit 7 set, the time elapsed during each logged function is calculated, and information on the number of times a function is called and by which function it was called is reported.

128

If this property has the bit 8 set, debugging information for NFJAVA is reported in the debugging file.

256

If this property has the bit 9 set, the call stack is printed for every debug message.

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.

Compatibility

The nCipherKM JCA/JCE CSP supports both module-protected keys and OCS-protected keys. The CSP currently supports 1/N OCSs and a single protection type for each nCipherKM JCE KeyStore.

You can use the nCipherKM JCA/JCE CSP with Security Worlds that comply with FIPS 140‑2 at either Level 2 or Level 3.

In a Security World that complies with FIPS 140-2 Level 3, it is not possible to import keys generated by other JCE providers.

The nCipherKM JCA/JCE CSP supports load-sharing for keys that are stored in the nCipherKM KeyStore. This feature allows a server to spread the load of cryptographic operations across multiple connected HSMs, providing greater scalability.

We recommend that you use load-sharing unless you have existing code that is designed to run with multiple HSMs. To share keys with load-sharing, you must create a 1/N OCS with at least as many cards as you have HSMs. All the cards in the OCS must have the same pass phrase.
The nCipherKM JCA/JCE CSP does not support HSM Pool mode. If you want to use HSM Pool mode with a Java application that only uses module protected keys, one option may be to use the Sun PKCS #11 provider to access the nShield PKCS #11 library instead of using nCipherKM JCA/JCE CSP.

Keys generated or imported by the nCipherKM JCA/JCE CSP are not recorded into the Security World until:

  1. The key is added to an nCipherKM KeyStore (by using a call to setKeyEntry() or setCertificateEntry()).

  2. That nCipherKM KeyStore is then stored (by using a call to store()).

The pass phrase used with the KeyStore must be the pass phrase of the card from the OCS that protects the keys in the KeyStore.

nShield PKCS #11 library

To use the nShield PKCS #11 library, you must tell the application the name and location of the library. The exact method for doing this depends on the application.

Instructions for using the nShield PKCS #11 library with specific applications are available from Entrust nShield Technical Support, https://nshieldsupport.entrust.com.

Depending on the application, you may need to set the path and library name %NFAST_HOME%\toolkits\pkcs11\cknfast.dll in a dialog or configuration file.

The nShield PKCS #11 library has security options which you must configure before you use the PKCS #11 library. For more information, see PKCS #11 library with Security Assurance Mechanism.

From version 1.7, the nShield PKCS #11 library can be used with FIPS 140-2 Level 3 compliant Security Worlds. This version of the library also introduces load‑sharing mode. This feature provides support for multiple hardware security modules that are connected to a single server, spreading the load of cryptographic operations between the HSMs in order to provide scalability in terms of performance.

To share OCS protected keys with load‑sharing mode, you must create a 1/N OCS that contains at least as many cards as you have HSMs. All the cards on the OCS must have the same passphrase.

With module firmware version 2.65.2 or later, if your application only uses module protected keys, you can use HSM Pool mode as an alternative to using load-sharing mode. HSM Pool mode supports returning or adding a hardware security module to the pool without restarting the system.

If you are using the preload command-line utility in conjunction with the nShield PKCS #11 library, you can create K/N OCSs.

Choosing functions

Some PKCS #11 applications enable you to choose which functions you want to perform on the PKCS #11 token and which functions you want to perform in your application.

The following paragraphs in this section describe the functions that an nShield HSM can provide.

Generating random numbers and keys

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.

Digital signatures

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

  • DSA

  • RSA

  • DES3_MAC

  • AES

  • ECDSA (if the appropriate feature is enabled)

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.

Asymmetric encryption

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.

Symmetric encryption

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

  • DES

  • Triple DES

  • AES

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.

Message digest

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.

Mechanisms

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

Key wrapping

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.

PKCS #11 library with Security Assurance Mechanism

It is possible for an application to use the PKCS #11 API in ways that do not necessarily provide the expected security benefits, or which might introduce additional weaknesses. For example, the PKCS #11 standard requires the nShield library to be able to generate keys that are extractable from the HSM in plaintext. An application could use this ability in error, when a secure key would be more appropriate.

The PKCS #11 library with the Security Assurance Mechanism (SAM), libcknfast, can help users to identify potential weaknesses, and help developers create secure PKCS #11 applications more easily.

The SAM in the PKCS #11 library is intended to detect operations that reveal questionable behavior by the application. If these occur, the application fails with an explanation of the cause of failure.

After a review of your security policy and the way the application uses the PKCS #11 library with the SAM, if there are questionable operations that are considered to be acceptable and pose no security risk, the PKCS #11 library can be configured to permit some, or all, of them by means of the CKNFAST_OVERRIDE_SECURITY_ASSURANCES environment variable (described in CKNFAST_OVERRIDE_SECURITY_ASSURANCES).

To ensure the security of your keys, you must review any messages returned by the PKCS #11 library before changing the settings of the CKNFAST_OVERRIDE_SECURITY_ASSURANCES environment variable.

The CKNFAST_OVERRIDE_SECURITY_ASSURANCES environment variable uses a semicolon separated list of parameters, with associated values, to explicitly allow operations that could compromise the security of cryptographic keys if the operations are not well understood.

If no parameters, or the none parameter, are supplied to the CKNFAST_OVERRIDE_SECURITY_ASSURANCES, the PKCS #11 library fails to perform the operation in question, and issues a warning, when the following operations are detected:

  • Creating short‑term session keys as long‑term objects

  • Creating keys that can be exported as plain text

  • Importing keys from external sources

  • Creating or importing wrapping keys

  • Creating or importing unwrapping keys

  • Creating keys with weak algorithms (such as DES)

  • Creating keys with short key lengths.

For more information about parameters and diagnostic warnings, see CKNFAST_OVERRIDE_SECURITY_ASSURANCES.

Key security

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.

Using the nShield PKCS #11 library

After you have loaded the nShield PKCS #11 library, it is added to your application’s list of cryptographic HSMs or PKCS #11 slots.

Whether or not the library uses load‑sharing mode depends on the value of the CKNFAST_LOADSHARING environment variable, described in CKNFAST_LOADSHARING. Whether or not the library uses HSM Pool mode depends on the value of the CKNFAST_HSM_POOL environment variable, described in CKNFAST_HSM_POOL.

nShield PKCS #11 library with load‑sharing mode

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:

  • Be used to support session objects

  • Be used to create module-protected keys

  • Not be used to create private objects.

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.

nShield PKCS #11 library with HSM Pool mode

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

nShield PKCS #11 library without load‑sharing

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

The entry called accelerator cannot be used to create private objects. It can be used to create module-protected keys.

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.

nShield PKCS #11 library with the preload utility

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.

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_FAKE_ACCELERATOR_LOGIN

  • CKNFAST_HSM_POOL

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

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_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_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_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

  • unwrap_mech

  • 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:

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.

unwrap_mech

The unwrap_mech parameter allows you to create keys with CKA_UNWRAP=true and CKA_DECRYPT=false.

By default, when unwrap_mech is not supplied as a parameter for CKNFAST_OVERRIDE_SECURITY_ASSURANCES, trying to create a key with CKA_UNWRAP=true and CKA_DECRYPT=false fails with CKR_TEMPLATE_INCONSISTENT.

When CKA_UNWRAP is set to true and CKA_DECRYPT is not specified in the template, then CKA_DECRYPT is automatically set to true.

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 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_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-2 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 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.

Checking the installation of the nShield PKCS #11 library

After you have created a Security World, ensure that the nShield PKCS #11 library has been successfully installed by using the ckcheckinst command-line utility.

To verify the installation of the nShield PKCS #11 library, follow these steps:

  1. Give the command ckcheckinst.

    If you have an invalid Security World (for example, if all your HSMs are in the initialization state), ckcheckinst quits with the following error message:

    ckcheckinst: C_Initialize failed rv = 00000006
Is the security world initialized? (Use nfkminfo to check)

    If your Security World is valid, ckcheckinst displays information similar to the following:

    PKCS#11 library interface version 2.40
 flags 0
 manufacturerID "nCipher Corp. Ltd "
 libraryDescription "nFast PKCS#11 1.#.# "
 implementation version 1.##
 Load sharing and Failover enabled

slot Status Label
===== ====== ===== 0 Fixed token "accelerator "
1 Operator card "card2 "
2 Operator card "card3 "
Select slot Number to run library test or 'R'etry or to 'E'xit:

    In this example output:

    • PKCS #11 library interface version 2.40 refers to the version of the PKCS #11 specification supported

    • implementation version 1.## refers to the version of the nCipher PKCS #11 library

    • Loadsharing and Failover enabled is shown if load‑sharing has been enabled. Alternatively Pool mode enabled is shown if Pool mode has been enabled.

    Slots that contain a valid Operator Card are indicated by the status Operator card and the card’s label. A fixed token is always available and is listed as slot 0.

    If you insert a blank card or an unrecognized card (for example, an Operator Card from a different Security World or an Administrator Card), this is indicated in the Status column. The corresponding slot number is not available.

    If you are using the preload command-line utility in conjunction with the nShield PKCS #11 library, you can only see the token that you loaded with the preload utility. In load-sharing mode, the loaded card set is used to set the environment variable CKNFAST_CARDSET_HASH, so only this card set is visible as a slot.

    If there is no card in a slot, ckcheckinst displays No token present beside the relevant slot numbers.

    ckcheckinst gives you the following choices:

    No removable tokens present.
Please insert an operator card into at least one available slot and
enter 'R' retry.
If you have not created an operator card or there are no physical slots, enter a fixed token slot number,
or 'E' to exit this program and create a card set before continuing.

  2. If there are no available slots with cards in them, you can choose one of the following actions:

    • Insert a valid Operator Card, and press R

    • choose a fixed token slot

    • Press E to quit, then create an OCS, and run ckcheckinst again.

    When there is at least one slot with a valid token, input a slot number, and press Enter. In a FIPS 140-2 Level 3 compliant Security World, ckcheckinst prompts you to enter the passphrase for the selected Operator Card.

  3. Type the passphrase, and press Enter.

    ckcheckinst displays the results of the tests:

    Test Pass/Failed
---- -----------
1 Generate RSA key pair Pass
2 Generate DSA key pair Pass
3 Encryption/Decryption Pass
4 Signing/Verify Pass
Deleted test keys ok
PKCS11 Library test successful.

    If any tests fail, ckcheckinst displays a message indicating the failure and quits. It does not run any subsequent tests.

    If ckcheckinst fails:

    • Check that the hardserver is running

    • Use the enquiry and nfkminfo world.

    If all seems in order, reinstall the nShield library.

How the nShield PKCS #11 library protects keys

Session objects are created on an HSM and never leave that HSM. The following table lists the protection for different types of PKCS #11 token objects:

Smart card Slot Accelerator Slot

Private Token Object

Operator Card Set

not supported

Public Token Object

Security World

Security World

Public key

well known HSM key

well known HSM key

Operator Card Set

The object is stored as an nShield key blob encrypted by the OCS key. You must log in to this OCS before you can load this object.

security world

The object is stored as an nShield key blob encrypted by the Security World key. This object can be loaded on to any HSM in the Security World. The nShield PKCS #11 library only allows access if a card from this OCS is present.

well-known module key

Public keys are encrypted under a well‑known HSM key. This encryption is for programming convenience only and does not provide security. These keys can be loaded on any nShield HSM.

nShield native and custom applications

Use the nShield native option for applications that were written using nShield key management software and that expect keys to be both protected by the Security World and stored in the Security World data structure.

Use the custom external application option for applications that were written using nShield key management software and that expect their keys to be in standalone files.

KeySafe does not place any restrictions on the OCS that is used to protect nShield native or custom application keys. You must make sure that your application is capable of loading the card set.

CodeSafe applications

If you have enabled the Secure Execution Engine (SEE), your system can run CodeSafe applications that implement special functionality.

If you wish to use the SEE to run applications, it must have been ordered and enabled as described in Enabling optional features.

An SEE application is typically a standalone SEE machine that is loaded automatically by the hardserver (for example, a CodeSafe C application).

Check the documentation that your application vendor supplies for information about any signatures that you may require to set up and use the application, as well as for any other installation and configuration information.

CodeSafe applications are standalone applications, but each CodeSafe C application can consist of multiple parts, and its installation can include several configuration steps. For instructions on installing and configuring each application, see your application vendor’s documentation.

To use a standalone application:

  1. Ensure that the SEE machine for the application is in the directory %NFAST_HOME%\ custom-seemachines on the remote file system.

    If an SEE machine has previously been loaded on the HSM, press the Clear button on the front of the unit before proceeding to the next step. This clears the current SEE machine from memory.

  2. From the main menu on the front panel of the HSM, select CodeSafe.

  3. To enable the HSM to publish the SEE World for multiple clients, enter the following information when prompted:

    • The name of the SEE machine file.

    • The name of the user data file, if required.

    • The type of custom SEE machine you are using (select SEElib or BSDlib sockserv).

      This option is only available if you have provided a valid user data file in step 2. If BSDlib sockserv is selected, worldid_pubname, postload_prog, and postload_args will be passed to load_seemachine . For detailed descriptions of the options in this section, see load_seemachine.

    • The ID of the SEE World to create.

      This option is only available if you have selected the SEElib option in the previous step.
To use see-sock-serv directly, you must select BSDlib sockserv.

Remotely loading and updating SEE machines

The SEE remote push facility allows the remote deployment of CodeSafe SEE machines to an Connect, negating the need to physically visit the HSM to load or update the SEE machine. This is achieved by editing the configuration file on the RFS for a specific Connect to specify the new SEE machine, then setting a configuration flag in the config file to true.

Before configuring a module to autonomously run an SEE machine and accept updates using the RFS, that module must first be set up to accept remotely-pushed configurations, see Configuring auto push.

For more information about configuring log file storage options, see Configuring log file storage.

To configure an Connect module to autonomously run an SEE machine and accept updates using the RFS:

  1. Copy the existing config file to a new file called config.new.

  2. In the load_seemachine section of the config.new file for the remote module, add or amend the following settings:

    pull_rfs=true
machine_file=mymachinename.sar
userdata=myuserdata.sar
worldid_pubname=publ_name
    These settings specify the type, name and user data of the SEE machine you wish to load. For more information about each setting, see load_seemachine.
    For CodeSafe Direct, the userdata file must be packed as a SAR file.
    The remote module will load the new SEE machine in place of any existing SEE machine. If no machine_file value is set, then pushing the config file will remove any existing machines on the unit.

  3. In the sys_log section of the config.new file for the remote module, add or amend the following settings:

    behaviour=push
push_interval=1
    These settings control how and where log messages are written. Using the example above, messages will be written to the system.log and hardserver.log files of the module, which are accessible using the remote file system. You may wish to revise the push_interval to a higher value once the Connect has successfully loaded the new SEE machine.

  4. Run nopclearfail to clear the module, followed by enquiry to check that the module is ready.

  5. Run cfg-pushnethsm to push the new config file to the module.

To load a new SEE machine to multiple Connect modules, we recommend scheduling down time for each HSM, upgrading them on a per HSM basis. Each Connect configuration file is specific to an individual HSM and each configuration file should be updated separately to load the new SEE machine.

Microsoft CAPI CSP

We provide a Cryptographic Service Provider (CSP) that implements the Cryptographic API (CAPI) supported in Windows 2003 and later.

Installing the CAPI CSP

A shortcut to the CSP installation wizard is placed in the Start menu under All Programs > nCipher when installing the Security World Software. If you want to use 32-bit applications with the nShield CAPI provider run the 32-bit installation wizard to install the CAPI CSP, and if you want to use 64-bit applications with the nShield CAPI provider run the 64-bit CSP installation wizard to install the CAPI CSP.

You can also use the CSP installation wizard to load existing Security Worlds, see Adding an HSM to a Security World with the CSP or CNG wizard, generate new Operator Card Sets, see Creating an Operator Card Set with the CSP or CNG wizard, and configure the set-up parameters of the CAPI CSP including HSM Pool mode.

With module firmware version 2.65.2 or later, if your application only uses module protected keys, you can use HSM Pool mode with multiple hardware security modules. HSM Pool mode exposes a single pool of HSMs and supports returning or adding a hardware security module to the pool without restarting the system. With a FIPS 140-2 Level 3 Security World, keys cannot be created in HSM Pool mode, however keys created outside HSM Pool mode can be used in HSM Pool mode.

The CSP installation wizard is not suitable for creating complex Security World setups. When creating such Security Worlds, or if you require more flexibility than the CSP installation wizard provides, we recommend following the instructions in Creating a Security World using new-world.

Use the standard Security World utility nfkmverify to check the security of all stored keys in the Security World; nfkminfo, nfkmcheck and other standard utilities can also be used to assist in this process.

The CSP installation wizard registers the CAPI CSP as a key provider on your system.

Importing a key

Use the cspimport utility to move keys between containers or to import a pre-generated NFKM key into a container. For more information about using the cspimport utility, run cspimport specifying either the --help or --usage options.

Supported algorithms

The nShield CSPs support a similar range of algorithms to the Microsoft CSP.

Symmetric algorithms

  • CALG_DES

  • CALG_3DES_112 (double-DES)

  • CALG_3DES

  • CALG_RC4

  • CALG_AES_128

  • CALG_AES_192

  • CALG_AES_256

Asymmetric algorithms

  • CALC_RSA_SIGN (only Enhanced RSA and AES Cryptographic Provider)

  • CALC_RSA_KEYX (only Enhanced RSA and AES Cryptographic Provider)

  • CALC_DSA_SIGN (only Enhanced DSS and Diffie-Hellman Cryptographic Provider and DSS Signature Cryptographic Provider)

  • CALC_DSS_SIGN (only Enhanced DSS and Diffie-Hellman Cryptographic Provider)

  • CALC_DH_KEYX (only Enhanced DSS and Diffie-Hellman Cryptographic Provider)

  • CALC_DH_SF (only Enhanced DSS and Diffie-Hellman Cryptographic Provider)

  • CALC_DH_EPHEM (only Enhanced DSS and Diffie-Hellman Cryptographic Provider)

Hash algorithms

  • CALG_SHA1

  • CALG_SHA256

  • CALG_SHA384

  • CALG_SHA512

  • CALG_SSL3_SHAMD5

  • CALG_MD5

  • CALG_MAC

  • CALG_HMAC

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.

Container storage format

Versions of the CSP later than 1.11.0 have an updated container storage mechanism. CSP containers are now stored as part of the Security World instead of in the Windows registry file.
Versions of the CSP later than 1.11.0 use a non-backwards-compatible container and key storage format. If you are installing version 1.11.0 or later of the CSP over older versions, you must run the cspmigrate utility in order to convert containers and keys from the old system to the new system.

CSP versions 1.11.0 and later have a number of advantages over older versions:

  • The CSP state is easily mirrored between multiple machines simply by copying the contents of the Key Management Data directory or by sharing the Key Management Data directory across a network.

  • The CSP key files can have arbitrary names (previously, the names of key files were linked to their key type and their container name). This new method facilitates the importation of existing Security World keys into the CSP.

  • Every different container is now guaranteed to have a distinct storage location. There were circumstances in CSP versions older than 1.11.0 in which two containers with similar names could have shared the same keys wrongly.

However, there are some points to bear in mind concerning CSP versions 1.11.10 and later:

  • If you want to share the same key between multiple computers, we supply the cspimport utility for transferring keys between containers.

  • Any existing containers with older versions of the CSP must be migrated to the new format. We provide a utility, cspmigrate, to migrate containers from the old to the new system.

Utilities for the CAPI CSP

To help you migrate from Windows registry-based CSP container storage to the new CSP format, CSP version 1.11.0 and later provides you with a set of utilities. The new CSP format stores all information about a Security World in the Key Management Data directory. There are also utilities to manage the interfaces between the MSCAPI library and the module.

These utilities are:

Utility Description

cspcheck

This utility checks that CSP container files are intact and uncorrupted, and also that referenced key files exist. Use cspcheck in conjunction with nfkmcheck, but run nfkmcheck first in order to test the integrity of your Security World files.

cspimport

This utility allows you to insert keys manually into existing CSP containers.

This utility has two modes that either allow you to change a container’s key association to that of an arbitrary Security World key or to copy CSP keys between containers.

cspmigrate

This utility moves the CSP container information from the registry into the Security World. If a new container already exists and has a key in it, and an identically-named old container exists with the same key, the utility asks you which key to keep. You can either:

Enter -q to keep the new keys.

Enter -f to overwrite new keys with old keys.

cspnvfix

Regenerate the NVRAM key counter area for a specified nShield CSP key.

csptest

Test the installed Cryptographic Service Providers.

csputils

This utility lists CSP containers and provides detailed information about them. It can also be used to delete container files if the current user has administrative privileges.

configure-csp-poolmode

The --mscapi option allows HSM Pool mode to be enabled or disabled for the nShield CAPI CSP without using the CSP wizard.

keytst

This utility displays information about existing CSP key containers by using the Microsoft CryptoAPI. If you have the appropriate permissions, keytst also allows you to create containers and their keys, as well as delete containers.
Each of these commands has an -h option that displays the usage message for the command.

Uninstalling the CAPI CSP

To uninstall the CAPI CSP and unregister it as a cryptographic provider on your system, run the cngregister and cnginstall commands with the -U option. For more information, see Utilities for CNG.

Microsoft Cryptography API: Next Generation (CNG)

Cryptography API: Next Generation (CNG) is the successor to the Microsoft Cryptographic API (CAPI) and its long-term replacement. CNG is designed to be extensible at many levels and cryptography agnostic in its behavior.

The Security World Software implementation of Microsoft CNG is supported on Microsoft Windows Server 2016 and later releases. The nShield CNG CSP provides the benefits of hardware-based encryption accessed through the standard Microsoft API, and supports the National Security Agency (NSA) classified Suite B algorithms.

Configuring the nShield CNG CSP

The DLL files that support the nShield CNG CSP are installed during product installation. However, you need to register the CNG CSP without removing the provider DLL files from your system.

You can unregister the nShield CNG CSP without removing the provider DLL files from your system. After unregistering, you can reregister the nShield CNG CSP, removing the files from your system. For more information, see Unregistering or reregistering the CNG CSP.

You can completely uninstall the nShield CNG CSP, removing the files from your system. After uninstalling, you must reinstall the files and then reregister the CNG CSP before you can use it. For more information, see Unregistering or reregistering the CNG CSP.

Registering the CNG CSP

You can register the nShield CNG CSP with:

  • CNG Configuration Wizard

  • The cngregister command-line utility

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.

Registering the CNG CSP with the CNG Configuration Wizard

We recommend using the CNG Configuration Wizard to register the nShield CNG CSP. The product installation process places a shortcut to the CNG Configuration Wizard in the Start menu under All Programs > nCipher.

You can also use the CNG Configuration Wizard to load existing Security Worlds, see Adding an HSM to a Security World with the CSP or CNG wizard, generate new OCSs, see Creating an Operator Card Set with the CSP or CNG wizard, and configure the set-up parameters of the CNG CSP including HSM Pool mode.

With module firmware version 2.65.2 or later, if your application only uses module protected keys, you can use HSM Pool mode with multiple hardware security modules. HSM Pool mode exposes a single pool of HSMs and supports returning or adding a hardware security module to the pool without restarting the system. With a FIPS 140-2 Level 3 Security World, keys cannot be created in HSM Pool mode, however keys created outside HSM Pool mode can be used in HSM Pool mode.

To register the CNG CSP with the CNG Configuration Wizard, you must have already created a Security World and chosen a key protection method, either module-protection or OCS-protection. If you chose OCS-protection, you must also have already created an OCS before you can register the nShield CNG CSP with the CNG Configuration Wizard.

The CNG Configuration Wizard is not suitable for creating complex Security World setups or for creating Security Worlds with the unit . When creating such Security Worlds, or if you require more flexibility than the CNG configuration wizard provides, we recommend following the instructions in Creating a Security World using new-world.

If you use the CNG Configuration Wizard to create a Security World (and, if appropriate, an OCS), the wizard automatically prompts you to register the CNG CSP after you have fulfilled the necessary prerequisites.

You can also use the CNG Configuration Wizard to change an existing configuration at any time by running the wizard as usual and choosing the Use the existing security world option on the Initial setup screen.

To register the CNG CSP with the CNG Configuration Wizard after the necessary key-protection prerequisites have been fulfilled:

  1. If the wizard is not already running:

    1. Run the wizard by double-clicking its shortcut in the Start menu under All Programs > nCipher.

      The wizard displays the welcome window.

    2. Click the Next button.

      The wizard allows you to configure HSM Pool mode for CNG.

    3. Click the Next button.

      If the prerequisite to create a Security World has been fulfilled, the wizard displays a confirmation screen.

    4. Click the Next button.

      The wizard displays a screen confirming that your Security World and (if you chose to create an OCS) an OCS have been created.

      If you chose module-protection for your keys, the wizard does not confirm that an OCS has been created.

  2. When the wizard has confirmed that it is ready to register the nShield CNG providers, click the Next button.

    The wizard registers the nShield CNG CSP.

    You cannot use the CNG Configuration Wizard to configure the nShield CNG providers for use as defaults. We recommend that you always use the nShield CNG providers by selecting them directly with the application that is using CNG.

When configuration of your nShield CNG CSP is complete, the wizard displays a confirmation screen.

Registering the CNG CSP with cngregister

You can use the cngregister command-line utility to register the nShield CNG CSP manually even if you have not already created a Security World (or, if you choose OCS-protection for your keys, even if you have not already created an OCS).

To register the nShield CNG CSP with the cngregister command-line utility, run the command without specifying any options:

cngregister
You cannot use the cngregister command-line utility to configure the nShield CNG providers for use as defaults. We recommend that you always use the cngregister command-line utility, see cngregister.

Unregistering or reregistering the CNG CSP

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:

cngregister -U

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.

If any applications or services are using the nShield CNG providers for key storage or cryptography, unregistering the CNG CSP, you can reregister it at any time as long as the files have not been uninstalled from your system.

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:

cngregister
You cannot use the cngregister command-line utility to configure the nShield CNG providers for use as defaults. We recommend that you always use the nShield CNG providers by selecting them directly with the application that is using CNG.

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

Uninstalling or reinstalling the CNG CSP

To uninstall the nShield CNG CSP:

  1. To remove any and all dependencies that you have set, run the command:

    ncsvcdep -x
    Always run ncsvcdep as a user with full administrative privileges.

  2. Unregister the nShield CNG CSP on your system by running the command:

    cngregister -U

    This command unregisters the CNG CSP, but does not remove the provider DLL files from your system.

  3. Uninstall the nShield CNG DLLs from your system:

    • On 32-bit versions of Windows, run the command:

      cnginstall -U

    • On 64-bit versions of Windows, run the command:

      cnginstall64 -U

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

  1. Reinstall the nShield CNG CSP files on your system:

    • On 32-bit versions of Windows, run the command:

      cnginstall -i

    • On 64-bit versions of Windows, run the command:

      cnginstall64 -i

  2. Reregister the nShield CNG CSP on your system by running the command:

    cngregister

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

Supported algorithms for CNG

This section lists the National Security Agency (NSA) classified Suite B algorithms supported by the nShield CNG providers.

The MQV algorithm is not supported by the nShield CNG providers.

Signature interfaces (key signing)

Interface name Type of support

RSA PKCS#1 v1

Hardware

RSA PSS

Hardware

DSA

Hardware

ECDSA_P224

Hardware

ECDSA_P256

Hardware

ECDSA_P384

Hardware

ECDSA_P521

Hardware
Hashes used with ECDSA must be of the same length or shorter than the curve itself. If you attempt to use a hash longer than the curve the operation returns NOT_SUPPORTED. In FIPS 140‑2 Level 3 Security Worlds ECDSA signing is only supported where the length of the curve is approximately the length of the hash.

Hashes

Hash name Type of support

SHA1

Hardware (HMAC only)/software

SHA256

Hardware (HMAC only)/software

SHA384

Hardware (HMAC only)/software

SHA512

Hardware (HMAC only)/software

SHA224

Hardware (HMAC only, requires firmware version 2.33.60 or later)/software

MD5

Hardware (HMAC only)/software
MD5 is not supported in FIPS 140‑2 mode.

Asymmetric encryption

Algorithm name Type of support

RSA Raw (NCRYPT_NO_PADDING_FLAG)

Hardware

RSA PKCS#1 v1 (NCRYPT_PAD_PKCS1_FLAG)

Hardware

RSA OAEP (NCRYPT_PAD_OAEP_FLAG)

Hardware

Symmetric encryption

Algorithm name Type of support

RC4

Hardware and Software (not supported in FIPS 140‑2 Level 3 mode)

AES ECB,CBC

Hardware and Software

DES ECB,CBC

Hardware and Software (DES is not supported in FIPS 140‑2 Level 3 mode)

3DES ECB,CBC

Hardware and Software

3DES_112 ECB,CBC

Hardware and Software

Key exchange

Protocol name Type of support

DH

Hardware

ECDH_P224

Hardware

ECDH_P256

Hardware

ECDH_P348

Hardware

ECDH_P521

Hardware
Elliptic curve cryptography algorithms must be enabled before use. Use the fet command-line utility with an appropriate certificate to enable a purchased feature. If you enable the elliptic curve feature on your modules after you first register the CNG providers, you must run the configuration wizard again for the elliptic curve algorithm providers to be registered.

Random Number Generation

Name Type of support

RNG

Hardware

Migrating keys for CNG

We provide functionality for migrating existing keys from other providers into the Security World Key Storage Provider. To identify installed providers, run the command:

cnglist --list-providers

To identify the keys that are available from a particular provider, run the command:

cnglist --list-keys --provider="ProviderName"

In this command, ProviderName is the name of the provider. The following command provides an example of identifying keys from the Security World Key Storage Provider:

cnglist --list-keys --provider="nCipher Security World Key Storage Provider"
MyApp Personal Data Key: RSA
CertReq-5eb45f6d-6798-472f-b668-288bc5d961da: ECDSA_P256 machine
WebServer Signing Key: DSA machine
ADCS-Root-Key: ECDSA_P521 machine
To list the keys available from the Security World Key Storage Provider, run the command cnglist --list-keys (without specifying the --provider option).

Importing a Microsoft CAPI key into the Security World Key Storage Provider

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:

cngimport -m --csp="Microsoft Strong Cryptographic Provider"
 -k "EXAMPLE_CAPICONTAINER"
    "EXAMPLE_IMPORTED_SIGNATURE_CAPICONTAINER"
    "EXAMPLE_IMPORTED_KEYEXCHANGE_CAPICONTAINER"

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

cnglist --list-keys
EXAMPLE_IMPORTED_SIGNATURE_CAPICONTAINER: RSA
EXAMPLE_IMPORTED_KEYEXCHANGE_CAPICONTAINER: DH

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

cngimport -m -s --csp="Microsoft Strong Cryptographic Provider"
 --key="EXAMPLE_CAPICONTAINER"
       "EXAMPLE_IMPORTED_SIGNATURE_ONLY_CAPICONTAINER"

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

cnglist --list-keys
EXAMPLE_IMPORTED_SIGNATURE_ONLY_CAPICONTAINER: RSA
The cngimport option -m/--migrate cannot be used to migrate nShield CAPI container keys to CNG. For information about importing nShield CAPI container keys into CNG, see Importing a Microsoft CNG key into the Security World Key Storage Provider.

Importing a Microsoft CNG key into the Security World Key Storage Provider

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

cngimport -m
 -k "EXAMPLE_RSA_1024"
    "IMPORTED_RSA_1024"

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

cnglist --list-keys
 IMPORTED_RSA_1024: RSA

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

cnglist --list-keys --provider="Microsoft Software Key Storage Provider"
 EXAMPLE_RSA_1024
Certain applications, such as Certificate Services, create keys using the Microsoft Software Key Storage Provider which cannot be exported. Attempting to import such a key into the nShield provider results in the following message: 
cngimport -m -k WIN-KQ1Z6JMCUTB-CA WIN-ncipher-CA
Unable to continue.
This key can not be exported from Microsoft Software Key Storage Provider.

Importing a Security World key into the Security World Key Storage Provider

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

cngimport --import --key=nfkmsimple1 --appname=simple nfkmsimple1
Found key 'nfkmsimple1'
Importing NFKM key.. done

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

cnglist --list-keys
nfkmsimple1: RSA

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

csputils -l
File ID    Container name       Container owner      DLL name   S X
=========  ===================  ===================  =========  = =
31e994f07  CONTAINER2           SYWELL\Administrato  ncsp       * *
3a2b082a8  CAPICONTAINER        SYWELL\Administrato  ncsp       * *
2 containers and 4 keys found.
Run the csputils command with the -l and -m options to migrate an nShield CAPI machine container.

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

csputils -d -n CAPICONTAINER
Detailed report for container ID #3a2b082a8f2ee1a5acb756d5e95b09817072807a
Filename:       key_mscapi_container-3a2b082a8f2ee1a5acb756d5e95b09817072807a
Container name: CAPICONTAINER
User name:      SYWELL\Administrator
User SID:       s-1-5-21-352906761-2625708315-3490211485-500
CSP DLL name:   ncsp.dll
Filename for signature key is key_mscapi_ce51a0ee0ea164b993d1edcbf639f2be62c53222
  Key was generated by the CSP
  Key hash:    ce51a0ee0ea164b993d1edcbf639f2be62c53222
  Key is recoverable.
Key is cardset protected.
Cardset name:             nopin
     Sharing parameters:       1 of 1 shares required.
Cardset hash:             d45b30e7b60cb226f5ade5b54f536bc1cc465fa4
     Cardset is non-persistent.
Filename for key exchange key is key_mscapi_dbd84e8155e144c59cf8797d16e7f8bd19ac446a
  Key was generated by the CSP
  Key hash:    dbd84e8155e144c59cf8797d16e7f8bd19ac446a
  Key is recoverable.
Key is cardset protected.
Cardset name:             nopin
     Sharing parameters:       1 of 1 shares required.
Cardset hash:             d45b30e7b60cb226f5ade5b54f536bc1cc465fa4
     Cardset is non-persistent.
1 container and 2 keys found.

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:

cngimport --import --key="ce51a0ee0ea164b993d1edcbf639f2be62c53222" --
appname="mscapi" Signature_Key_Imported_From_nCipher_CAPI
Found unnamed key
Importing NFKM key.. done

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

cnglist --list-keys
Signature_Key_Imported_From_nCipher_CAPI: RSA
cngsoak: ECDH_P256

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

Using CAPI keys in CNG

We now provide the capability to use keys generated by CAPI in CNG applications. This is provided through the standard NCryptOpenKey CNG API call. Passing either AT_SIGNATURE or AT_KEYEXCHANGE as the dwLegacyKeySpec parameter and the CAPI container name as the pszKeyName parameter will invoke this mode of operation. The CAPI key will be loaded into the CNG provider and will behave as if it was a CNG key. Any key authorization required will be handled with a user interface being invoked to prompt the application user to insert the smart card or enter appropriate pass phrases. There is support for Key Usage and Key Counting properties.

The CNG application has to be written such that it calls NCryptOpenKey to open a CAPI key explicitly.

Utilities for CNG

Use the nfkmverify command-line utility to check the security of all stored keys in the Security World. Use nfkminfo, nfkmcheck, and other command-line utilities to assist in this process.

The following table lists the utilities specific to the nShield CNG CSP:

x86 x64 Utility description

cngimport.exe

cngimport.exe

This key migration utility is used to migrate Security World, CAPI, and CNG keys to the Security World Key Storage Provider.

cnginstall.exe

cnginstall64.exe

This utility is the nShield CNG CSP installer. Only use this utility to remove or reinstall the provider DLLs and associated registry entries manually.

cnglist.exe

cnglist.exe

This utility lists information about CNG CSP.

cngregister.exe

cngregister.exe

This is the nShield CNG CSP registration utility. You can use it to unregister and re-register the

ncsvcdep.exe

ncsvcdep.exe

This utility is the service dependency tool. You can configure some service based applications, such as Microsoft Certificate Services and IIS, to use the nShield CNG CSP. The

These utilities are located in the bin directory of your Security World Software installation (for example, %NFAST_HOME%\bin).

On 64-bit versions of Windows, both the 32-bit and 64-bit versions of the listed utilities are installed. When working on an 64-bit version of Windows, always ensure that you use the 64-bit version of the utility (if one is available).

cngimport

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

cnginstall

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:

cnginstall -U

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

ncksppt.dll removed.
nckspsw.dll removed.
ncpp.dll removed.

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:

cngregister

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

cngregister

Use cngregister to unregister the nShield CNG CSP manually.

To unregister the nShield CNG CSP, run the command:

cngregister -U

This command produces output for the form:

Unregistered provider 'nCipher Primitive Provider'
Unregistered provider 'nCipher Security World Key Storage Provider'

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

If any applications or services are using the nShield CNG CSP for key storage or cryptography, unregistering it can cause system instability.

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:

cngregister
You cannot use the cngregister command-line utility to configure the nShield CNG providers for use as defaults. We recommend that you always use the nShield CNG providers by selecting them directly with the application that is using CNG.

cngsoak

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

  • Signing a hash (cngsoak --sign)

  • encryption (cngsoak --encrypt)

  • key exchange (cngsoak --keyx)

  • key generation (cngsoak --generate).

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

  • The time in second that cngsoak has been running

  • the total number of operations completed

  • the number of operations completed in last second

  • the average number of operations completed each second.

ncsvcdep

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:

ncsvcdep -l

Output from this command has the form:

Installed Services (Count - "Display Name" - "Service Name")
0 - "Application Experience" - "AeLookupSvc"
1 - "Application Layer Gateway Service" - "ALG"
2 - "Application Information" - "Appinfo"
3 - "Application Management" - "AppMgmt"
4 - "Windows Audio Endpoint Builder" - "AudioEndpointBuilder"
.
.
108 - "nFast Server" - "nFast Server"
109 - "Active Directory Certificate Services" - "CertSvc"
Always run ncsvcdep as a user with full administrative privileges.

To set a dependency, run the command:

ncsvcdep -a "DependentService"

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:

ncsvcdep -a "CertSvc"
Dependency change succeeded.

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

ncsvcdep -r "CertSvc"
Dependency change succeeded.

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

ncsvcdep -x
Microsoft Certificate Services require that the certsvc service is made dependent on the hardserver.
Microsoft Internet Information Services require that the http service is made dependent on the hardserver.

cnglist

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:

cnglist --list-providers

Output from this command is of the form:

Microsoft Primitive Provider
Microsoft Smart Card Key Storage Provider
Microsoft Software Key Storage Provider
Microsoft SSL Protocol Provider
nCipher Primitive Provider
nCipher Security World Key Storage Provider

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

cnglist --list-algorithms

Output from this command has the form:

BCryptEnumAlgorithms(BCRYPT_CIPHER_OPERATION):
  Name                           Class      Flags
  AES                            0x00000001 0x0
  RC4                            0x00000001 0x0
  DES                            0x00000001 0x0
  DESX                           0x00000001 0x0
  3DES                           0x00000001 0x0
  3DES_112                       0x00000001 0x0
BCryptEnumAlgorithms(BCRYPT_HASH_OPERATION):
  Name                           Class      Flags
  SHA1                           0x00000002 0x0
  MD2                            0x00000002 0x0
  MD4                            0x00000002 0x0
  MD5                            0x00000002 0x0
  SHA256                         0x00000002 0x0
  SHA384                         0x00000002 0x0
  SHA512                         0x00000002 0x0
  AES-GMAC                       0x00000002 0x0
  SHA224                         0x00000002 0x0
BCryptEnumAlgorithms(BCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION):
  Name                           Class      Flags
  RSA                            0x00000003 0x0

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:

cnglist --list-algorithms --keystorage --nc

Output from this command has the form:

NCryptEnumAlgorithms(NCRYPT_CIPHER_OPERATION) no supported algorithms
NCryptEnumAlgorithms(NCRYPT_HASH_OPERATION) no supported algorithms
NCryptEnumAlgorithms(NCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION):
  Name                           Class      Operations Flags
  RSA                            0x00000003 0x00000014 0x0
NCryptEnumAlgorithms(NCRYPT_SECRET_AGREEMENT_OPERATION):
  Name                           Class      Operations Flags
  DH                             0x00000004 0x00000008 0x0
  ECDH_P224                      0x00000004 0x00000008 0x0
  ECDH_P256                      0x00000004 0x00000008 0x0
  ECDH_P384                      0x00000004 0x00000008 0x0
  ECDH_P521                      0x00000004 0x00000008 0x0
NCryptEnumAlgorithms(NCRYPT_SIGNATURE_OPERATION):
  Name                           Class      Operations Flags
  RSA                            0x00000003 0x00000014 0x0
  DSA                            0x00000005 0x00000010 0x0
  ECDSA_P224                     0x00000005 0x00000010 0x0
  ECDSA_P256                     0x00000005 0x00000010 0x0
  ECDSA_P384                     0x00000005 0x00000010 0x0
  ECDSA_P521                     0x00000005 0x00000010 0x0

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:

cnglist --list-algorithms --provider="Microsoft Software Key Storage Provider"

Output from this command has the form:

Microsoft Software Key Storage Provider
NCryptEnumAlgorithms(NCRYPT_CIPHER_OPERATION) no supported algorithms
NCryptEnumAlgorithms(NCRYPT_HASH_OPERATION) no supported algorithms
NCryptEnumAlgorithms(NCRYPT_ASYMMETRIC_ENCRYPTION_OPERATION):
  Name                           Class      Operations Flags
  RSA                            0x00000003 0x00000014 0x0
NCryptEnumAlgorithms(NCRYPT_SECRET_AGREEMENT_OPERATION):
  Name                           Class      Operations Flags
  DH                             0x00000004 0x00000008 0x0
  ECDH_P256                      0x00000004 0x00000018 0x0
  ECDH_P384                      0x00000004 0x00000018 0x0
  ECDH_P521                      0x00000004 0x00000018 0x0
NCryptEnumAlgorithms(NCRYPT_SIGNATURE_OPERATION):
  Name                           Class      Operations Flags
  RSA                            0x00000003 0x00000014 0x0
  DSA                            0x00000005 0x00000010 0x0
  ECDSA_P256                     0x00000005 0x00000010 0x0
  ECDSA_P384                     0x00000005 0x00000010 0x0
  ECDSA_P521                     0x00000005 0x00000010 0x0
configure-csp-poolmode

The configure-csp-poolmode utility allows HSM Pool mode to be enabled or disabled for the nShield CNG CSP without using the CNG wizard.

To enable HSM Pool mode for CNG run the command:

configure-csp-poolmode --cng --enable

To disable HSM Pool mode for CNG run the command:

configure-csp-poolmode --cng --disable

To remove HSM Pool mode setting for CNG from the registry, use the command:

configure-csp-poolmode --cng --remove