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.
You must add the user of any application that uses an nShield HSM to the group nfast before the application runs. |
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:
-
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.
-
-
For Java 7 and 8 only. Copy the
CipherKM.jar
file to the extensions folder of your local Java Virtual Machine installation from the following directory:-
/opt/nfast/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 theJAVA_HOME
environment variable). If you are using Java 11 you do not need to copy the jar file. -
-
Add
$JAVA_HOME/bin
to your PATH system variable -
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:
-
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. -
Extract the files
local_policy.jar
andUS_export_policy.jar
from Java Virtual Machine vendor’s Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy File archive. -
Copy the extracted files
local_policy.jar
andUS_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 theJAVA_HOME
environment variable).Copying the files local_policy.jar
andUS_export_policy.jar
into the appropriate folder must overwrite any existing files with the same names.
-
-
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 ofsecurity.provider.1
, bothcom.ncipher.provider.km.nCipherKM
and another provider). -
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 /opt/nfast/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:
-
Check that you have configured ports correctly, as described in Installing the nCipherKM JCA/JCE CSP. For more information about hardserver configuration file settings, see server_startup.
-
Check that you have created a Security World. If you have not created a Security World, create a Security World. For more information, see Creating a Security World.
-
If you have already created a Security World, repeat the nCipherKM JCA/JCE CSP installation process as described in Installing the nCipherKM JCA/JCE CSP.
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 /opt/nfast/java/classes com.ncipher.provider.InstallationTest
Alternatively, you can specify the location of the nCipherKM jar on the classpath:
java --class-path /opt/nfast/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 |
---|---|
|
This property is a bit mask for which different values specify different debugging functions; the default value is |
|
This property specifies a path to the file to which logging output is to be written.
Set this property if the In a production environment, we recommend that you disable debug logging to prevent sensitive information being made available to an attacker. |
|
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 |
|
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. |
|
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. |
|
If the value of this property is set to |
|
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. |
|
The default value for this property is |
|
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. |
|
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 |
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 |
---|---|
|
If this property has no bits set, no debugging information is reported. This is the default setting. |
|
If this property has the bit 1 set, minimal debugging information (for example, version information and critical errors) is reported. |
|
If this property has the bit 2 set, comprehensive debugging information is reported. |
|
If this property has the bit 3 set, debugging information relating to creation and destruction of memory and HSM resources is reported. |
|
If this property has the bit 4 set, |
|
If this property has the bit 5 set, |
|
If this property has the bit 6 set, context information is reported with each debugging message (for example, the |
|
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. |
|
If this property has the bit 8 set, debugging information for NFJAVA is reported in the debugging file. |
|
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:
-
The key is added to an nCipherKM KeyStore (by using a call to
setKeyEntry()
orsetCertificateEntry()
). -
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
/opt/nfast/toolkits/pkcs11/libcknfast.so
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_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
.
This file must be in the /opt/nfast/
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 |
---|---|
|
None (default setting) |
|
Fatal error |
|
General error |
|
Fix-up error |
|
Warnings |
|
Application errors |
|
Assumptions made by the nShield PKCS #11 library |
|
API function calls |
|
API return values |
|
API function argument values |
|
Details |
|
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_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
-
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:
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
andC_SignUpdate
-
C_Verify
andC_VerifyUpdate
-
C_Encrypt
andC_EncryptUpdate
-
C_Decrypt
andC_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.
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-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. |
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:
-
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. AlternativelyPool 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 thepreload
utility. In load-sharing mode, the loaded card set is used to set the environment variableCKNFAST_CARDSET_HASH
, so only this card set is visible as a slot.If there is no card in a slot,
ckcheckinst
displaysNo 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.
-
-
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. -
-
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
andnfkminfo
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.
You may need to use the hardserver
, loadmache
, and tct2
utilities when configuring and loading an application; see the CodeSafe Developer Guide for more information.
To use see-sock-serv directly, you must select BSDlib sockserv .
|