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

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.

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 8 (or Java 1.8x)

  • Java 11

  • Java 17

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 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 8 only. Copy the nCipherKM.jar file to the extensions folder of your local Java Virtual Machine installation from the following directory:

    • 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 Runtime Environment (JRE)

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

  3. Add to your PATH system variable

  4. For Java 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 Runtime Environment (JRE)

      In these paths, 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 file located in the security directory for your local Java Virtual Machine (JVM) installation: security.provider.<n>=com.ncipher.provider.km.nCipherKM, where <n> is the position in the list of providers, for example:

    security.provider.1=sun.security.provider.Sun
security.provider.2=sun.security.rsa.SunRsaSign
security.provider.3=com.sun.net.ssl.internal.ssl.Provider
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=sun.security.jgss.SunProvider
security.provider.6=com.sun.security.sasl.Provider
security.provider.7=com.ncipher.provider.km.nCipherKM

    For Java 11 and Java 17 you do not need to specify the fully qualified class name for the provider. Instead you can just use the provider name: security.provider.<n>=nCipherKM.

    The JVM uses this file to select the provider from which to request a mechanism instance. If your JCE application does not request the nCipherKM provider by name, or if it fails to load keys, you might need to move the nCipherKM provider to the top of the list: security.provider.1=com.ncipher.provider.km.nCipherKM. Do not change the relative order of the other providers in the list.

    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). If you add the nCipherKM provider as security.provider.1, ensure that the subsequent providers are re-numbered correctly.

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

java com.ncipher.provider.InstallationTest

For Java 11 and Java 17:

For this command to work, you must have added 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 and Java 17

The nCipherKM Provider has been implemented as a named module. This means that, for Java 11 and Java 17, 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.

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

keytool

Use the Java keytool utility to read and edit an nShield KeyStore. You must specify the correct nCipher.sworld KeyStore type when you run the keytool utility.

To generate a new key in an OCS-protected KeyStore with the Java keytool utility, run the following command:

keytool -genkeypair -storetype nCipher.sworld -keyalg RSA -sigalg SHA1withRSA -storepass <KeyStore_passphrase> -keystore <KeyStore_path>

In this example command, KeyStore_passphrase is the passphrase for the OCS protecting the KeyStore. KeyStore_path is the path to the KeyStore.

To generate a new key in a module-protected KeyStore with the Java keytool utility, run the following command:

keytool -J-Dprotect=module -J-DignorePassphrase=true -genkeypair -storetype nCipher.sworld -keyalg RSA -sigalg SHA1withRSA -keystore <KeyStore_path>

In this example command, <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 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 -DignorePassphrase=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.

ignorePassphrase

If the value of this property is set to true, the nCipherKM provider ignores the passphrase 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 passphrase be provided; setting this property allows a dummy passphrase 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 at either Level 2 or Level 3.

In a Security World that complies with FIPS 140 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 passphrase.
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 passphrase used with the KeyStore must be the passphrase 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 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 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 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_JCE_COMPATIBILITY

  • CKNFAST_LOADSHARING

  • CKNFAST_LOAD_KEYS

  • CKNFAST_NO_ACCELERATOR_SLOTS

  • CKNFAST_NO_SYMMETRIC

  • CKNFAST_NO_UNWRAP

  • CKNFAST_NONREMOVABLE

  • CKNFAST_NVRAM_KEY_STORAGE

  • CKNFAST_OVERRIDE_SECURITY_ASSURANCES

  • CKNFAST_RELOAD_KEYS

  • CKNFAST_SEED_MAC_ZERO

  • CKNFAST_SESSION_THREADSAFE

  • CKNFAST_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.

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_FAKE_ACCELERATOR slots allow the creation of objects with CKA_PRIVATE=TRUE in the template even though the login is "fake" and the objects are not private.

  • Examining the attributes shows CKA_PRIVATE as FALSE.

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

CKNFAST_HSM_POOL

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

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

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

CKNFAST_JCE_COMPATIBILITY

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

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:

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. 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 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 "nCipher 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 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 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 nShield HSM, 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 nShield HSM 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, the module must be configured to accept remotely-pushed configurations. See Pushing configuration files to the nShield HSM.

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

To configure an nShield HSM 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 nShield HSM 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 nShield HSMs, we recommend scheduling down time for each HSM, upgrading them on a per HSM basis. Each nShield HSM configuration file is specific to an individual HSM and each configuration file should be updated separately to load the new SEE machine.