PKCS11

This chapter is intended for application developers who are writing PKCS #11 applications.

For an introduction to the PKCS #11 user library, including information about the environment variables and utilities available, see the User Guide for your HSM.

Before using the nShield PKCS #11 libraries, we recommend that you read http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html.

The following diagram illustrates the way that an nShield PKCS #11 library works with the nShield APIs.

This guide does not address how the nShield PKCS #11 libraries map PKCS #11 functions to nCore API calls within the library.

PKCS #11 developer libraries

The nShield PKCS #11 libraries, libdcknfast.so and libcknfast.a (nShield tools only) on Linux, and cknfast.lib and cknfast.dll on Windows are provided so that you can integrate your PKCS #11 applications with the nShield hardware security modules.

The nShield PKCS #11 libraries:

Provide the PKCS #11 mechanisms listed in Mechanisms
Help you to identify potential security weaknesses, enabling you to create secure PKCS #11 applications more easily.

PKCS #11 security assurance mechanism

It is possible for an application to use the PKCS #11 API in ways that can introduce potential security weaknesses. For example, it is a requirement of the PKCS #11 standard that the nShield PKCS #11 libraries are able to generate keys that are explicitly exportable in plain text. An application could use this ability in error when a secure key would be more appropriate.

The nShield PKCS #11 libraries are provided with a configurable security assurance mechanism (SAM). SAM helps prevent PKCS #11 applications from performing operations through the PKCS #11 API that may compromise the security of cryptographic keys. Operations that reveal questionable behavior by the application fail by default with an explanation of the cause of failure.

If you decide that some operations that carry a higher security risk are acceptable to you, then you can reconfigure the nShield PKCS #11 library to permit these operations by means of the environment variable CKNFAST_OVERRIDE_SECURITY_ASSURANCES. You must think carefully, however, before permitting operations that could compromise the security of cryptographic keys. For more information about the environment variable and its parameters, see the User Guide for your HSM.

It is your responsibility as a security developer to familiarize yourself with the PKCS #11 standard and to ensure that all cryptographic operations used by your application are implemented in a secure manner.

If no parameters are supplied to the environment variable, the nShield PKCS #11 library fails and issues a warning, with an explanation, when the following operations are detected:

Short term session keys created as long term objects
Keys that can be exported as plain text are created
Keys are imported from external sources
Wrapping keys are created or imported
Unwrapping keys are created or imported
Keys with weak algorithms (for example, DES) are created
Keys with short key length are created.

PKCS #11 with load-sharing mode

The behavior of the nShield PKCS #11 library varies depending on which of load-sharing mode, HSM Pool mode or neither or these is enabled. If you have enabled load-sharing mode, the nShield PKCS #11 library creates one virtual slot for each OCS and, optionally, also creates one slot for the HSM or HSMs. Softcards appear as additional virtual slots once enabled.

Load-sharing mode must be enabled in PKCS #11 in order to use softcards.

Whether or not load-sharing mode is enabled is determined by the state of the CKNFAST_LOADSHARING environment variable.

Load-sharing mode enables you to load a single PKCS #11 token onto several nShield HSMs to improve performance. To enable successful load-sharing with an OCS protected key:

You must have an Operator Card from the OCS inserted into every slot from the same 1/N card set
All the Operator Cards must have the same passphrase.

The nShield-specific API calls, C_LoginBegin, C_LoginNext, and C_LoginEnd do not function in load-sharing mode. K/N support for card sets in load-sharing mode is only available if you first use preload to load the logical token.

Logging in

If you call C_Login without a token present, it fails (as expected) unless you are using a persistent token with preload or using only module-protected keys. Therefore, your application should prompt users to insert tokens before logging in.

The nShield PKCS #11 library removes the nShield logical token when you call C_Logout, whether or not there is a smart card in the reader.

If there are any cards from the OCS present when you call C_Logout, the PKCS #11 token remains present but not logged-in until all cards in the set are removed. If there are no cards present, the PKCS #11 token becomes not present.

The CKNFAST_NONREMOVABLE environment variable is only available for persistent tokens. When the variable is set, the rules for recognizing new cards are overridden, and the only way to invoke a new token is to call C_Finalize or C_Initialize.

Session objects

Session objects are loaded on all modules.

Module failure

If a subset of the modules fails, the nShield PKCS #11 library handles commands using the remaining modules. If a module fails, the single cryptographic function that was running on that module will fail, and the nShield PKCS #11 library will return a PKCS #11 error. Subsequent cryptographic commands will be run on other modules.

Compatibility

Before the implementation of load-sharing, the nShield PKCS #11 library puts the electronic serial number in both the slotinfo.slotDescription and tokeninfo.serialNumber fields. If you have enabled load-sharing, the tokeninfo.serialNumber field displays the hash of the OCS.

Restrictions on function calls in load-sharing mode

The following function calls are not supported in load-sharing mode:

C_LoginBegin (nShield-specific call to support K/N card sets)
C_LoginNext (nShield-specific call to support K/N card sets)
C_LoginEnd (nShield-specific call to support K/N card sets).

The following function calls are supported in load-sharing mode only when using softcards:

C_InitToken
C_InitPIN
C_SetPIN.

To use C_InitToken, C_InitPIN, or C_SetPIN in load-sharing mode, you must have created a softcard with the command ppmk -n before selecting the corresponding slot.

The C_InitToken function is not supported for use in non-load-sharing FIPS 140-2 Level 3 Security Worlds.

PKCS #11 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 supports module protected keys but does not support token-protected keys. 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.

Whether or not HSM Pool mode is enabled is determined by the state of the CKNFAST_HSM_POOL environment variable.

In FIPS 140-2 Level 3 Security Worlds, keys cannot be created in HSM Pool mode, however keys created outside HSM Pool mode can be used in HSM Pool mode.

Module failure

If a subset of the modules in the HSM pool fail, the nShield PKCS #11 library handles commands using the remaining modules. When a module fails, any cryptographic functions that were running on that module are restarted on one of the remaining modules. If all of the modules in the HSM pool fail, the nShield PKCS #11 library will return a PKCS #11 error.

Module recovery

If a failed module recovers and remains part of the Security World, it is automatically returned to the HSM Pool and the nShield PKCS #11 library can use it for new commands. If a new module is added to the system that is accessible to the host running the PKCS #11 application, then once the Security World has been loaded onto this HSM, then it is automatically added to the HSM Pool and the nShield PKCS #11 library can use it for new commands.

Restrictions on function calls in HSM Pool mode

The following function calls are not supported in HSM Pool mode:

C_LoginBegin
C_LoginNext
C_LoginEnd
C_InitToken
C_InitPIN
C_SetPIN

PKCS #11 with key reloading

The nShield PKCS #11 library is capable of reloading keys to nShield HSMs after a PKCS #11 application has started. The PKCS #11 library will attempt to reload the keys to all HSMs from which keys have been unloaded after the application was started, for example, if the HSM was cleared. This also means that if an application uses HSMs that became unusable during runtime, the PKCS #11 library will re-add these HSMs into the group of HSMs in a single Security World when they become usable again. The PKCS #11 library will also attempt to reload the keys on new HSMs that become usable after the application has started, for example if you enroll a new HSM into the Security World. The application can then use the HSM for key operations.

The default behavior without PKCS #11 key reloading is that when an HSM is removed from the group of HSMs in a Security World, it is not re-added for PKCS #11 until the user’s application is restarted.

The CKNFAST_RELOAD_KEYS environment variable determines whether key reloading mode is enabled.

Load-sharing mode must be enabled in PKCS #11 to use key reloading mode. If load-sharing is not enabled, it is enabled automatically if CKNFAST_RELOAD_KEYS is enabled.

Key reloading is not supported for session keys.

Usage under preload

PKCS #11 key reloading only reloads keys. It must also operate under a preload session during which preload is reloading tokens that protect the keys used by PKCS #11, in high availability mode. When the PKCS #11 application is using a token-protected key, preload should first be run to reload the token while PKCS #11 is reloading the key. For information on running preload for PKCS #11 key reloading, see section PKCS #11 and JCE in the User Guide for your HSM.

PKCS #11 key reloading is also supported for module-protected keys, but the PKCS #11 application must still be run under a preload application which is reloading tokens for another key.

Either run the PKCS #11 application as a subprocess of preload, or in a separate command window ensuring the preload file set for preload matches the one set for PKCS #11. See section nShield PKCS #11 library with the preload utility in the User Guide for your HSM.

The application will attempt to reload keys when supported functions are called, see Supported function calls.

Persistent preload files

The preload file persists on disk after the preload process has terminated. Therefore, a PKCS #11 application in key reloading mode should not be run with an NFAST_NFKM_TOKENSFILE that points to a preload file from an old (non-running) preload process.

Supported function calls

Key reloading is attempted whenever a key is used for a cryptographic operation. For signing, verifying, encrypting, and decrypting, the functions are as follows:

C_SignInit
C_VerifyInit
C_EncryptInit
C_DecryptInit

On a call to any of these functions, the PKCS #11 library will do the following:

Checks if preload has reloaded any token objects on any HSMs since the last time one of the above functions was called. This is done by checking if the preload file has been modified. If not, there is nothing to reload.
If reload is required, reloads any keys that are protected by the newly-loaded tokens on all usable HSMs in the group.

Retrying key reloads

PKCS #11 can fail to reload a key due to transient or genuine errors. An example for a transient error is when an HSM has not finished reinitializing in time for a key to be reloaded. An example for a genuine error is when the key is invalid. In case of a failure, PKCS #11 will attempt to reload the key every time one of the functions in Supported function calls is called for a further 5 minutes before abandoning the key reload on that HSM.

Adding new HSMs

With key reloading enabled using the CKNFAST_RELOAD_KEYS environment variable, the PKCS #11 library can add new HSMs to its internal list of usable modules. HSMs are new if they were not present when PKCS #11 applications were initialized. When key reloading is not enabled, PKCS #11 applications must be restarted before the new HSMs can be used.

The PKCS #11 library supports a maximum of 32 HSMs. If you have already reached 32 HSMs and you add a new HSM, then the PKCS #11 library will not be able to add this module. If an HSM is removed from the Security World or otherwise becomes unusable, it is still counted towards this limit. The application must be restarted to remove the removed or unusable HSM from the list.

PKCS #11 without load-sharing mode or HSM Pool mode

The nShield PKCS #11 library makes each nShield module appear to your PKCS #11 application as two or more PKCS #11 slots.

The first slot represents the module itself. This token:

Appears as a non-removable hardware token and has the flag CKF_REMOVABLE not set
Has the flag CKF_LOGIN_REQUIRED not set (C_Login always fails on this flag).

Applications can ignore this slot, but you can use the slot to store public session objects or for functions that do not use objects (such as C_GenerateRandom) even when the smart-card is not present.

The second slot represents the smart-card reader. This token:

appears as a PKCS #11 slot, potentially containing a removable hardware token that has the flag CKF_REMOVABLE set
is marked as removed if the smart card is removed from the physical slot
has the flag CKF_LOGIN_REQUIRED
allows the creation of token objects.

To use softcards with PKCS #11, load-sharing mode must be enabled.

A PKCS #11 token can support multiple concurrent sessions on multiple applications. However, by default, only one token may be logged in to a given slot at a given time (see K/N support for PKCS #11). By default, when you insert a new card into a slot, the nShield PKCS #11 library automatically logs out any token that had been logged in to the slot previously.

The C_InitToken function is not supported for use in non-load-sharing FIPS 140-2 Level 3 Security Worlds.

K/N support for PKCS #11

If you use the nShield PKCS #11 library without load-sharing mode or HSM Pool mode, you can implement K/N card set support in two ways:

By using the nShield-specific API calls, C_LoginBegin, C_LoginNext, and C_LoginEnd
By using the preload command-line utility to load the logical token first.

Generating and deleting NVRAM-stored keys with PKCS #11

You can use the nShield PKCS #11 library to generate keys stored in nonvolatile memory (up to a maximum of 12 keys) if you have set the CKNFAST_NVRAM_KEY_STORAGE environment variable.

Generating NVRAM-stored keys

To generate NVRAM-stored keys with the nShield PKCS #11 library:

Load (or reload) the ACS using the preload command-line utility. Open a command-line window and give the command:
```
preload --admin=NV pause
```
After loading the ACS, remove the Administrator Cards from the module.
Ensure that the CKNFAST_NVRAM_KEY_STORAGE environment variable is set. If this variable is not set, the keys generated are not stored in NVRAM.
Open a second command-line window, and give the command:
```
preload --cardset-name=<name> <pkcs11app>
```
where <name> is the cardset name and <pkcs11app> is the name of your PKCS #11 application.
Generate the NVRAM-stored keys that you need (up to a maximum of 12 keys) as normal.
Stop or close <pkcs11app>.

Return to the command-line window you opened in step 1 and terminate the preload --admin=NV pause process.

Do not allow the preload --admin=NV pause process to run continuously. Run this process only when generating or deleting NVRAM-stored keys. As usual, remove the Administrator Cards when they are not in use and store them safely.

Unset the CKNFAST_NVRAM_KEY_STORAGE environment variable.
Restart <pkcs11app>.

You can use the newly generated NVRAM-stored keys in the same way as other PKCS #11 keys. You can also generate any number of standard keys (not stored in NVRAM) in the usual way.

Deleting NVRAM-stored keys

To delete NVRAM-stored keys with the nShield PKCS #11 library:

Load (or reload) the ACS using the preload command-line utility. Open a command-line window and give the command:
```
preload --admin=NV pause
```

After loading the ACS, remove the Administrator Cards from the module. Ensure that the CKNFAST_NVRAM_KEY_STORAGE environment variable is set.

If you attempt to delete NVRAM-stored keys without the CKNFAST_NVRAM_KEY_STORAGE environment variable set, only the key blob stored on hard disk is deleted. The keys remain in NVRAM on the module. Use the nvram-sw command-line utility to fully remove the NVRAM-stored keys. For more information, see the User Guide.

Open a second command-line window, and give the command:
```
preload --cardset-name=<name> -M <pkcs11app>
```
where <name> is the cardset name and <pkcs11app> is the name of the PKCS #11 application that you use to delete the keys.
Delete the NVRAM-stored keys as you would delete normal keys.
Stop or close <pkcs11app>.

Return to the command-line window you opened in step 1 and terminate the preload --admin=NV pause process.

Do not allow the preload --admin=NV pause to run continuously. Run this process only when generating or deleting NVRAM-stored keys. As usual, remove the Administrator Cards when they are not in use and store them safely.

Unset the CKNFAST_NVRAM_KEY_STORAGE environment variable.

PKCS #11 Security Officer

The PKCS #11 Security Officer is a role that is created and managed by the cksotool utility. The utility creates a softcard and key, which are used to perform operations within the nShield PKCS #11 library as the Security Officer. The idents of the generated softcard and key are ncipher-pkcs11-so-softcard and ncipher-pkcs11-so-key, respectively. They are used during Security Officer operations to provide the cryptographic security.

ncipher-pkcs11-so-softcard does not appear in the result of C_GetSlotList and therefore cannot be used to create PKCS #11 keys, or have its PIN changed using C_SetPIN.

To act as the Security Officer within the nShield PKCS #11 library, the Security Officer token and key must be preloaded using the preload utility:

preload -s ncipher-pkcs11-so-softcard pause

The PKCS #11 session must also be logged in as the user CKU_SO. preload is used so that virtual-slots in load-sharing can be logged into using the usual PKCS #11 API. This allows Security Officer operations to be performed on keys protected by any token.

It is strongly advised that operations that require loading the PKCS #11 Security Officer token are performed by a dedicated tool, and not integrated into a main application.

nShield-specific PKCS #11 API extensions

nShield K/N card sets use nShield-specific API calls. These calls can be used by the application in place of the standard C_Login to provide log-in to a card set with a K parameter greater than 1. The API calls include three functions, C_LoginBegin, C_LoginNext and C_LoginEnd.

The login sequence must occur in the same session.

You cannot use the API calls in load-sharing mode. To use K/N card sets in load-sharing mode, use preload to load the logical token first. The API calls also work in a non-load-sharing FIPS 140-2 Level 3 Security Worlds.

C_LoginBegin

Similar to C_Login, this function initiates the log-in process, ensures that the session is valid, and ensures that the user is not in load-sharing mode.

The pulK and pulN return values provide the caller with the number of card requests required. An example of the use of C_LoginBegin is shown here:

C_LoginBegin (CK_SESSION_HANDLE hSession, /* the session's handle */
              CK_USER_TYPE userType, /* the user type */
              CK_ULONG_PTR pulK, /* cards required to load logical token*/
              CK_ULONG_PTR pulN /* Number of cards in set */)

C_LoginNext

C_LoginNext is called K times until the required number of cards (for the given card set) have been presented. This function checks the Security World info to ensure that the card has changed each time. It also checks for the correct passphrase before loading the card share. pulSharesLeft allows the user application to assess the number of cards loaded to the number of cards required.

CK_RV gives various values that allow the user to access the application state using standard PKCS #11 return values (such as CKR_TOKEN_NOT_RECOGNIZED). These values reveal such information as whether the card is the same, whether the card is foreign or blank, and whether the passphrase was incorrect.

An example of the use of C_LoginNext is shown here:

C_LoginNext (CK_SESSION_HANDLE hSession, /* the session's handle */
             CK_USER_TYPE userType, /* the user type*/
             CK_CHAR_PTR pPin, /* the user's PIN*/
             CK_ULONG ulPinLen, /* the length of the PIN */
             CK_ULONG_PTR pulSharesLeft /* Number of shares still needed */)

C_LoginEnd

C_LoginEnd is called after all the shares are loaded. It constructs the logical token from the presented shares and then loads the private objects protected by the card set that are available to it:

C_LoginEnd (CK_SESSION_HANDLE hSession, /* the session's handle */
            CK_USER_TYPE userType /* the user type*/)

There must be no other calls between the functions, in that or any other session on the slot. In particular, a call that updates the Security World while using a card that has been removed at the time (for example, because a second card from the set is about to be inserted) returns CKR_DEVICE_REMOVED in the same way that it would for a single card. All sessions are then closed and the log-in process is aborted.

If other functions are accidentally called during the log-in cycle, then slot.loadcardsetstate is checked before updating the Security World. If the log-in process has not been completed, other functions return CKR_FUNCTION_FAILED and allow you to continue with the log-in process.

Compiling and linking

The following options are available if you want to integrate the nShield PKCS #11 library with your application. Depending on how your application integrates with PKCS #11 libraries, you can:

statically link the nShield PKCS #11 library directly into your application
dynamically link the nShield PKCS #11 library into your application
create a plug-in shared library that contains the nShield position-independent code object files together with your own adaptation facilities.

You may freely supply your users with the compiled library files linked into your application or into a plug-in library used for your application.

The nShield PKCS #11 library includes the PKCS #11 header files pkcs11.h, pkcs11t.h, and pkcs11f.h from the RSA Data Security, Inc. Cryptoki Cryptographic Token Interface. Any work based on this interface is bound by the following terms of RSA Data Security, Inc. Licence, which states:

License is also granted to make and use derivative works provided that such works are identified as derived from the RSA Data Security, Inc. Cryptoki Cryptographic Token Interface in all material mentioning or referencing the derived work.

For more information about using the available libraries, see the Include Paths and Linking section in the nCore API Documentation on the Security World Software installation media.

Windows

All versions are built with Visual Studio 2017. Entrust supplies the following files:

%NFAST_HOME%\bin\cknfast.dll and %NFAST_HOME%\toolkits\pkcs11\cknfast.dll: a dynamically linked library

Both files are identical.
%NFAST_HOME%\c\ctd\lib\cknfast.lib: a stub for applications that link to cknfast.dll
%NFAST_HOME%\c\ctd\lib\libdcknfast.lib: a static library with position-independent code

Linux

Entrust supplies the following libraries:

libcknfast.so, libcknfast.so.a, or libcnfast.sl: a standard, dynamically linked, shared library that can be used to create applications that must be dynamically linked with the nShield libraries at run time. On platforms where thread safety requires programs to be compiled differently from non-threaded programs, these libraries are compiled thread-safe.
libcknfast.a: a standard, non-shared library used to statically link an application.
libcknfast_thrpic.a: a non-shared library, compiled as threadsafe position-independent code.

On the Developer installation media, each library is provided with a corresponding set of header files. All the header files for each version are very similar, but some header files (particularly those that contain information about compiler and configuration options) differ by version.

These types of library are provided compiled with the following C compilers for Linux libc6.11:

Library Type Build Notes

Library Type	Build Notes
`/opt/nfast/c/ctd/gcc/lib`	This type of library is built with gcc 4.9.2 in 32-bit mode.
`/opt/nfast/c/csd/gcc/lib`	This type of library is built with gcc 4.9.2 in 64-bit mode.

/opt/nfast/c/ctd/gcc/lib

This type of library is built with gcc 4.9.2 in 32-bit mode.

/opt/nfast/c/csd/gcc/lib

This type of library is built with gcc 4.9.2 in 64-bit mode.

Objects

Token objects are not stored in the nShield module. Instead, they are stored in an encrypted and integrity-protected form on the hard disk of the host computer. The key used for this encryption is created by combining information stored on the smart card with information stored in the nShield module and with the card passphrase.

Session keys are stored on the nShield module, while other session objects are stored in host memory. Token objects on the host are created in the kmdata directory. In order to access token objects, the user must have:

the smart card
the passphrase for the smart card
an nShield module containing the module key used to create the token
the host file containing the nShield key blob protecting the token object.

The nShield PKCS #11 library can be used to manipulate Data Objects, Certificate Objects, and Key Objects.

Certificate Objects and Data Objects

The nShield PKCS #11 library does not parse Certificate Objects or Data Objects.

The size of Data Objects is limited by what can be fitted into a single command (under most circumstances, this limit is 8192 bytes).

Key Objects

The following restrictions apply to keys:

Key types	Restrictions
RSA	Modulus greater than or equal to 1024. The nShield PKCS #11 library requires all of the attributes for an RSA key object to be supplied, as listed in Table 26: "RSA Private Key Object Attributes" of PKCS #11 Cryptographic Token Interface Standard version 2.40.
DSA	Modulus greater than or equal to 1024 in multiples of 8 bits.
Diffie-Hellman	Modulus greater than or equal to 1024.

Key types

Restrictions

RSA

Modulus greater than or equal to 1024.

The nShield PKCS #11 library requires all of the attributes for an RSA key object to be supplied, as listed in Table 26: "RSA Private Key Object Attributes" of PKCS #11 Cryptographic Token Interface Standard version 2.40.

DSA

Modulus greater than or equal to 1024 in multiples of 8 bits.

Diffie-Hellman

Modulus greater than or equal to 1024.

Card passphrases

All passphrases are hashed using the SHA-1 hash mechanism and then combined with a module key to produce the key used to encrypt data on the nShield physical or software token. The passphrase supplied can be of any length.

The ckinittoken program imposes a 512-byte limit on the passphrase.

C_GetTokenInfo reports _MaxPinLen as 256 because some applications may have problems with a larger value.

When C_Login is called, the passphrase is used to load private objects protected by that card set on to all modules with cards from that set. Public objects belonging to that set are loaded on to all the modules. C_Login fails if any logical token fails to load. All cards in a card set must have the same passphrase.

The functions C_SetPIN, C_InitPIN, and C_InitToken are supported in load-sharing mode only when using softcards. To use these functions in load-sharing mode, you must have created a softcard with the command ppmk -n before selecting the corresponding slot.

The C_InitToken function is not supported for use in non-load-sharing FIPS 140-2 Level 3 Security Worlds.

Functions supported

The following sections list the PKCS #11 functions supported by the nShield PKCS #11 library. For a list of supported mechanisms, see Mechanisms.

Certain functions are included in PKCS #11 version 2.40 for compatibility with earlier versions only.

General purpose functions

The following functions perform as described in the PKCS #11 specification:

C_Finalize
C_GetInfo
C_GetFunctionList.

C_Initialize

If your application uses multiple threads, you must supply such functions as CreateMutex (as stated in the PKCS #11 specification) in the CK_C_INITIALIZE_ARGS argument.

Slot and token management functions

The following functions perform as described in the PKCS #11 specification:

C_GetSlotInfo
C_GetTokenInfo
C_GetMechanismList
C_GetMechanismInfo.

C_GetSlotList

This function returns an array of PKCS #11 slots. Within each module, the slots are in the order:

module(s)
smart card reader(s)
software tokens, if present.

Each module is listed in ascending order by nShield ModuleID.

C_GetSlotList returns an array of handles. You cannot make any assumptions about the values of these handles. In particular, these handles are not equivalent to the slot numbers returned by the nCore API command GetSlotList.

C_InitToken

C_InitToken sets the card passphrase to the same value as the current token’s passphrase and sets the CKF_USER_PIN_INITIALIZED flag.

This function is supported in load-sharing mode only when using softcards. To use C_InitToken in load-sharing mode, you must have created a softcard with the command ppmk -n before selecting the corresponding slot.

The C_InitToken function is not supported for use in non-load-sharing FIPS 140-2 Level 3 Security Worlds.

C_InitPIN

There is usually no need to call C_InitPIN, because C_InitToken sets the card passphrase.

Because the nShield PKCS #11 library can only maintain a single passphrase, C_InitPIN has the effect of changing the current token’s passphrase.

This function is supported in load-sharing mode only when using softcards. To use C_InitPIN in load-sharing mode, you must have created a softcard with the command ppmk -n before selecting the corresponding slot.

C_SetPIN

The card passphrase may be any value.

Because the nShield PKCS #11 library can only maintain a single passphrase, C_SetPIN has the effect of changing the current token’s passphrase or, if called in a Security Officer session, the card passphrase.

This function is supported in load-sharing mode only when using softcards. To use C_SetPIN in load-sharing mode, you must have created a softcard with the command ppmk -n before selecting the corresponding slot.

Standard session management functions

These functions perform as described in the PKCS #11 specification:

C_OpenSession
C_CloseSession
C_CloseAllSessions
C_GetOperationState
C_SetOperationState
C_Login
C_Logout

nShield session management functions

The following are nShield-specific calls for K/N card set support:

C_LoginBegin
C_LoginNext
C_LoginEnd
C_GetSessionInfo

ulDeviceError returns the numeric value of the last status, other than Status_OK, returned by the module. This value is never cleared. Status values are enumerated in the header file messages-args-en.h on the nShield Developer’s installation media. For descriptions of nShield status codes, see the nCore API Documentation (supplied as HTML).

Object management functions

These functions perform as described in the PKCS #11 specification:

C_CreateObject
C_CopyObject
C_DestroyObject
C_GetObjectSize
C_GetAttributeValue
C_SetAttributeValue
C_FindObjectsInit
C_FindObjects
C_FindObjectsFinal

Encryption functions

These functions perform as described in the PKCS #11 specification:

C_EncryptInit
C_Encrypt
C_EncryptUpdate
C_EncryptFinal

Decryption functions

These functions perform as described in the PKCS #11 specification:

C_DecryptInit
C_Decrypt
C_DecryptUpdate
C_DecryptFinal

Message digesting functions

The following functions are performed on the host computer:

C_DigestInit
C_Digest
C_DigestUpdate
C_DigestFinal

Signing and MACing functions

The following functions perform as described in the PKCS #11 specification:

C_SignInit
C_Sign
C_SignRecoverInit
C_SignRecover.

The functions C_SignUpdate and C_SignFinal are supported for:

CKM_SHA1_RSA_PKCS
CKM_MD5_RSA_PKCS.

Functions for verifying signatures and MACs

The following functions perform as described in the PKCS #11 specification:

C_VerifyInit
C_Verify
C_VerifyRecover
C_VerifyRecoverInit.

The C_VerifyUpdate and C_VerifyFinal functions are supported for:

CKM_SHA1_RSA_PKCS
CKM_MD5_RSA_PKCS

Dual-purpose cryptographic functions

The following functions perform as described in the PKCS #11 specification:

C_DigestEncryptUpdate
C_DecryptDigestUpdate.

The C_SignEncryptUpdate and C_DecryptVerifyUpdate functions are supported for:

CKM_SHA1_RSA_PKCS
CKM_MD5_RSA_PKCS

Key-management functions

The following functions perform as described in the PKCS #11 specification:

C_GenerateKey
C_GenerateKeyPair
C_WrapKey
C_UnwrapKey
C_DeriveKey

You can use the CKNFAST_OVERRIDE_SECURITY_ASSURANCES environment variable to modify the way that some functions, including key-management functions, are used.

Random number functions

The nShield module has an onboard, hardware random number generator to handle the following random number functions:

C_GenerateRandom
C_SeedRandom

For this reason, it does not use seed values, and the C_SeedRandom function returns CKR_RANDOM_SEED_NOT_SUPPORTED.

Parallel function management functions

The following functions are supported in the approved fashion by returning the PKCS #11 status CKR_FUNCTION_NOT_PARALLEL:

C_GetFunctionStatus
C_CancelFunction

Callback functions

There are no vendor-defined callback functions. Surrender callback functions are never called.

Mechanisms

The following table lists the mechanisms currently supported by the nShield PKCS #11 library and the functions available to each one. Entrust also provides vendor-supplied mechanisms, described in Vendor-defined mechanisms.

Some mechanisms may be restricted from use in Security Worlds conforming to FIPS 140-2 Level 3. See the User Guide for your HSM for more information.

Mechanism Encrypt & Decrypt Sign & Verify SR & VR Digest Gen. Key/Key Pair Wrap & Unwrap Derive Key

Mechanism	Encrypt & Decrypt	Sign & Verify	SR & VR	Digest	Gen. Key/Key Pair	Wrap & Unwrap	Derive Key
`CKM_AES_CBC_ENCRYPT_DATA`	—	—	—	—	—	—	Y
`CKM_AES_CBC_PAD`	Y	—	—	—	—	Y	—
`CKM_AES_CBC`	Y	—	—	—	—	Y¹	—
`CKM_AES_CMAC_GENERAL`	—	Y	—	—	—	—	—
`CKM_AES_CMAC`	—	Y	—	—	—	—	—
`CKM_AES_ECB_ENCRYPT_DATA`	—	—	—	—	—	—	Y
`CKM_AES_ECB`	Y	—	—	—	—	Y¹	—
`CKM_AES_KEY_GEN`	—	—	—	—	Y	—	—
`CKM_AES_KEY_WRAP`	—	—	—	—	—	Y	—
`CKM_AES_KEY_WRAP_PAD`²	Y	—	—	—	—	Y	—
`CKM_AES_KEY_WRAP_KWP`	Y	—	—	—	—	Y	—
`CKM_AES_MAC_GENERAL`	—	Y	—	—	—	—	—
`CKM_AES_MAC`	—	Y	—	—	—	—	—
`CKM_CONCATENATE_BASE_AND_KEY`	—	—	—	—	—	—	Y³
`CKM_DES_CBC_ENCRYPT_DATA`	—	—	—	—	—	—	Y
`CKM_DES_CBC_PAD`	Y	—	—	—	—	Y	—
`CKM_DES_CBC`	Y	—	—	—	—	Y	—
`CKM_DES_ECB_ENCRYPT_DATA`	—	—	—	—	—	—	Y
`CKM_DES_ECB`	Y	—	—	—	—	Y	—
`CKM_DES_KEY_GEN`	—	—	—	—	Y	—	—
`CKM_DES_MAC_GENERAL`	—	Y	—	—	—	—	—
`CKM_DES_MAC`	—	Y	—	—	—	—	—
`CKM_DES2_KEY_GEN`	—	—	—	—	Y	—	—
`CKM_DES3_CBC_ENCRYPT_DATA`	—	—	—	—	—	—	Y
`CKM_DES3_CBC_PAD`	Y	—	—	—	—	Y	—
`CKM_DES3_CBC`	Y	—	—	—	—	Y¹	—
`CKM_DES3_ECB_ENCRYPT_DATA`	—	—	—	—	—	—	Y
`CKM_DES3_ECB`	Y	—	—	—	—	Y¹	—
`CKM_DES3_KEY_GEN`	—	—	—	—	Y	—	—
`CKM_DES3_MAC_GENERAL`	—	Y	—	—	—	—	—
`CKM_DES3_MAC`	—	Y	—	—	—	—	—
`CKM_DH_PKCS_DERIVE`	—	—	—	—	—	—	Y
`CKM_DH_PKCS_KEY_PAIR_GEN`	—	—	—	—	Y	—	—
`CKM_DSA_KEY_PAIR_GEN`	—	—	—	—	Y	—	—
`CKM_DSA_PARAMETER_GEN`	—	—	—	—	Y	—	—
`CKM_DSA_SHA1`	—	Y	—	—	—	—	—
`CKM_DSA`	—	Y⁴	—	—	—	—	—
`CKM_EC_EDWARDS_KEY_PAIR_GEN`	—	—	—	—	Y⁵	—	—
`CKM_EC_KEY_PAIR_GEN`	—	—	—	—	Y⁶	—	—
`CKM_EC_MONTGOMERY_KEY_PAIR_GEN`	—	—	—	—	Y⁵	—	—
`CKM_ECDH1_DERIVE`	—	—	—	—	—	—	Y⁷
`CKM_ECDSA_SHA1`	—	Y	—	—	—	—	—
`CKM_EDDSA`	—	Y⁴, ⁸	—	—	—	—	—
`CKM_ECDSA`	—	Y⁴	—	—	—	—	—
`CKM_GENERIC_SECRET_KEY_GEN`	—	—	—	—	Y	—	—
`CKM_MD5_HMAC_GENERAL`	—	Y	—	—	—	—	—
`CKM_MD5_HMAC`	—	Y	—	—	—	—	—
`CKM_MD5`	—	—	—	Y	—	—	—
`CKM_NC_ECIES`	—	—	—	—	—	Y⁹	—
`CKM_NC_MD5_HMAC_KEY_GEN`	—	—	—	—	Y	—	—
`CKM_PBE_MD5_DES_CBC`	—	—	—	—	Y	—	—
`CKM_RIPEMD160`	—	—	—	Y	—	—	—
`CKM_RSA_9796`	—	Y⁴	Y⁴	—	—	—	—
`CKM_RSA_PKCS_KEY_PAIR_GEN`	—	—	—	—	Y	—	—
`CKM_RSA_PKCS_OAEP`	Y	—	—	—	—	Y	—
`CKM_RSA_PKCS_PSS`¹¹	Y	Y	—	—	—	—	—
`CKM_RSA_PKCS`	Y⁴	Y⁴	Y⁴	—	—	Y	—
`CKM_RSA_X_509`	Y⁴	Y⁴	Y⁴	—	—	X	—
`CKM_RSA_X9_31_KEY_PAIR_GEN`	—	—	—	—	Y	—	—
`CKM_SHA_1_HMAC_GENERAL`	—	Y¹⁰	—	—	—	—	—
`CKM_SHA_1_HMAC`	—	Y¹⁰	—	—	—	—	—
`CKM_SHA_1`	—	—	—	Y	—	—	—
`CKM_SHA1_RSA_PKCS_PSS`¹¹	—	Y	—	—	—	—	—
`CKM_SHA1_RSA_PKCS`	—	Y	—	—	—	—	—
`CKM_SHA224_HMAC_GENERAL`	—	Y¹⁰	—	—	—	—	—
`CKM_SHA224_HMAC`	—	Y¹⁰	—	—	—	—	—
`CKM_SHA224_RSA_PKCS_PSS`¹¹	—	Y	—	—	—	—	—
`CKM_SHA224`	—	—	—	Y	—	—	—
`CKM_SHA256_HMAC_GENERAL`	—	Y¹⁰	—	—	—	—	—
`CKM_SHA256_HMAC`	—	Y¹⁰	—	—	—	—	—
`CKM_SHA256_RSA_PKCS_PSS`¹¹	—	Y	—	—	—	—	—
`CKM_SHA256_RSA_PKCS`	—	Y	—	—	—	—	—
`CKM_SHA256`	—	—	—	Y	—	—	—
`CKM_SHA384_HMAC_GENERAL`	—	Y¹⁰	—	—	—	—	—
`CKM_SHA384_HMAC`	—	Y¹⁰	—	—	—	—	—
`CKM_SHA384_RSA_PKCS_PSS`¹¹	—	Y	—	—	—	—	—
`CKM_SHA384_RSA_PKCS`	—	Y	—	—	—	—	—
`CKM_SHA384`	—	—	—	Y	—	—	—
`CKM_SHA512_HMAC_GENERAL`	—	Y¹⁰	—	—	—	—	—
`CKM_SHA512_HMAC`	—	Y¹⁰	—	—	—	—	—
`CKM_SHA512_RSA_PKCS_PSS`¹¹	—	Y	—	—	—	—	—
`CKM_SHA512_RSA_PKCS`	—	Y	—	—	—	—	—
`CKM_SHA512`	—	—	—	Y	—	—	—
`CKM_WRAP_RSA_CRT_COMPONENTS`	—	—	—	—	—	Y¹²	—
`CKM_XOR_BASE_AND_DATA`	—	—	—	—	—	—	Y¹³

CKM_AES_CBC_ENCRYPT_DATA

—

CKM_AES_CBC_PAD

—

CKM_AES_CBC

—

Y¹

—

CKM_AES_CMAC_GENERAL

—

CKM_AES_CMAC

—

CKM_AES_ECB_ENCRYPT_DATA

—

CKM_AES_ECB

—

Y¹

—

CKM_AES_KEY_GEN

—

CKM_AES_KEY_WRAP

—

CKM_AES_KEY_WRAP_PAD²

—

CKM_AES_KEY_WRAP_KWP

—

CKM_AES_MAC_GENERAL

—

CKM_AES_MAC

—

CKM_CONCATENATE_BASE_AND_KEY

—

Y³

CKM_DES_CBC_ENCRYPT_DATA

—

CKM_DES_CBC_PAD

—

CKM_DES_CBC

—

CKM_DES_ECB_ENCRYPT_DATA

—

CKM_DES_ECB

—

CKM_DES_KEY_GEN

—

CKM_DES_MAC_GENERAL

—

CKM_DES_MAC

—

CKM_DES2_KEY_GEN

—

CKM_DES3_CBC_ENCRYPT_DATA

—

CKM_DES3_CBC_PAD

—

CKM_DES3_CBC

—

Y¹

—

CKM_DES3_ECB_ENCRYPT_DATA

—

CKM_DES3_ECB

—

Y¹

—

CKM_DES3_KEY_GEN

—

CKM_DES3_MAC_GENERAL

—

CKM_DES3_MAC

—

CKM_DH_PKCS_DERIVE

—

CKM_DH_PKCS_KEY_PAIR_GEN

—

CKM_DSA_KEY_PAIR_GEN

—

CKM_DSA_PARAMETER_GEN

—

CKM_DSA_SHA1

—

CKM_DSA

—

Y⁴

—

CKM_EC_EDWARDS_KEY_PAIR_GEN

—

Y⁵

—

CKM_EC_KEY_PAIR_GEN

—

Y⁶

—

CKM_EC_MONTGOMERY_KEY_PAIR_GEN

—

Y⁵

—

CKM_ECDH1_DERIVE

—

Y⁷

CKM_ECDSA_SHA1

—

CKM_EDDSA

—

Y⁴, ⁸

—

CKM_ECDSA

—

Y⁴

—

CKM_GENERIC_SECRET_KEY_GEN

—

CKM_MD5_HMAC_GENERAL

—

CKM_MD5_HMAC

—

CKM_MD5

—

CKM_NC_ECIES

—

Y⁹

—

CKM_NC_MD5_HMAC_KEY_GEN

—

CKM_PBE_MD5_DES_CBC

—

CKM_RIPEMD160

—

CKM_RSA_9796

—

Y⁴

—

CKM_RSA_PKCS_KEY_PAIR_GEN

—

CKM_RSA_PKCS_OAEP

—

CKM_RSA_PKCS_PSS¹¹

—

CKM_RSA_PKCS

Y⁴

—

CKM_RSA_X_509

Y⁴

—

CKM_RSA_X9_31_KEY_PAIR_GEN

—

CKM_SHA_1_HMAC_GENERAL

—

Y¹⁰

—

CKM_SHA_1_HMAC

—

Y¹⁰

—

CKM_SHA_1

—

CKM_SHA1_RSA_PKCS_PSS¹¹

—

CKM_SHA1_RSA_PKCS

—

CKM_SHA224_HMAC_GENERAL

—

Y¹⁰

—

CKM_SHA224_HMAC

—

Y¹⁰

—

CKM_SHA224_RSA_PKCS_PSS¹¹

—

CKM_SHA224

—

CKM_SHA256_HMAC_GENERAL

—

Y¹⁰

—

CKM_SHA256_HMAC

—

Y¹⁰

—

CKM_SHA256_RSA_PKCS_PSS¹¹

—

CKM_SHA256_RSA_PKCS

—

CKM_SHA256

—

CKM_SHA384_HMAC_GENERAL

—

Y¹⁰

—

CKM_SHA384_HMAC

—

Y¹⁰

—

CKM_SHA384_RSA_PKCS_PSS¹¹

—

CKM_SHA384_RSA_PKCS

—

CKM_SHA384

—

CKM_SHA512_HMAC_GENERAL

—

Y¹⁰

—

CKM_SHA512_HMAC

—

Y¹⁰

—

CKM_SHA512_RSA_PKCS_PSS¹¹

—

CKM_SHA512_RSA_PKCS

—

CKM_SHA512

—

CKM_WRAP_RSA_CRT_COMPONENTS

—

Y¹²

—

CKM_XOR_BASE_AND_DATA

—

Y¹³

The nShield library supports some mechanisms that are defined in versions of the PKCS #11 standard later than 2.01, although the nShield library does not fully support versions of the PKCS #11 standard later than 2.01.

In the table above:

Empty cells indicate mechanisms that are not supported by the PKCS #11 standard.
The entry Y indicates that a mechanism is supported by the nShield PKCS #11 library.
The entry X indicates that a mechanism is not supported by the nShield PKCS #11 library.

In the table above, annotations with the following numbers indicate:

¹ Wrap secret keys only (private key wrapping must use CBC_PAD).

² CKM_AES_KEY_WRAP_PAD has been deprecated and replaced by CKM_AES_KEY_WRAP_KWP.

³ Before you can create a key for use with the derive mechanism CKM_CONCATENATE_BASE_AND_KEY, you must first specify the CKA_ALLOWED_MECHANISMS attribute in the template with the CKM_CONCATENATE_BASE_AND_KEY set. Specifying the CKA_ALLOWED_MECHANISMS in the template enables the setting of the nCore level ACL, which enables the key in this derive key operation. For more information about the Security Assurance Mechanisms (SAMs) on the CKM_CONCATENATE_BASE_AND_KEY mechanism, see Mechanisms. About the CKA_ALLOWED_MECHANISMS attribute, see Attributes.

⁴ Single-part operations only.

⁵ CKA_EC_PARAMS is a DER-encoded PrintableString curve25519.

⁶ If no capabilities are specified in the template, for example the CKA_DERIVE, CKA_SIGN and CKA_UNWRAP attributes are omitted, then the default capability is sign/verify.

Key generation does calculate its own curves but, as shown in the PKCS #11 standard, takes the CKA_PARAMS, which contains the curve information (similar to that of a discrete logarithm group in the generation of a DSA key pair). CKA_EC_PARAMS is a Byte array which is DER-encoded of an ANSI X9.62 Parameters value. It can take both named curves and custom curves.

The following PKCS #11-specific flags describe which curves are supported:

CKF_EC_P: prime curve supported
CKF_EC_2M: binary curve supported
CKF_EC_PARAMETERS: supplying your own custom parameters is supported
CKF_EC_NAMECURVE: supplying a named curve is supported
CKF_EC_UNCOMPRESS: supports uncompressed form only, compressed form not supported.

⁷ The CKM_ECDH1_DERIVE mechanism is supported. However, the mechanism only takes a CK_ECDH1_DERIVE_PARAMS struct in which CK_EC_KDF_TYPE is CKD_NULL, CKD_SHA1_KDF, CKD_SHA224_KDF, CKD_SHA256_KDF, CKD_SHA384_KDF, or CKD_SHA512_KDF. For more information on CK_ECDH1_DERIVE_PARAMS, see the PKCS #11 standard.

For the pPublicData* parameter, a raw octet string value (as defined in section A.5.2 of ANSI X9.62) and DER-encoded ECPoint value (as defined in section E.6 of ANSI X9.62 or, in the case of CKK_EC_MONTGOMERY, RFC 7748) are now accepted.

⁸ Both the Ed25519 and Ed25519ph signature schemes are supported, The Ed25519 scheme requires either no CK_EDDSA_PARAMS to be passed or if it is passed it should have the following set:

phFlag to CK_FALSE
ulContextDataLen to 0.

The Ed25519ph signature scheme requires CK_EDDSA_PARAMS to have the following set:

phFlag to CK_TRUE
ulContextDataLen to 0.

⁹ Wrap secret keys only.

¹⁰ This mechanism depends on the vendor-defined key generation mechanism CKM_NC_SHA_1_HMAC_KEY_GEN, CKM_NC_SHA224_HMAC_KEY_GEN, CKM_NC_SHA256_HMAC_KEY_GEN, CKM_NC_SHA384_HMAC_KEY_GEN, or CKM_NC_SHA512_HMAC_KEY_GEN. For more information, see Vendor-defined mechanisms.

¹¹ The hashAlg and the mgf that are specified by the CK_RSA_PKCS_PSS_PARAMS must have the same SHA hash size. If they do not have the same hash size, then the signing or verify fails with a return value of CKR_MECHANISM_PARAM_INVALID.

The sLen value is expected to be the length of the message hash. If this is not the case, then the signing or verify again fails with a return value of CKR_MECHANISM_PARAM_INVALID. The Security World Software implementation of RSA_PKCS_PSS salt lengths are as follows:

Mechanism	Salt-length
SHA-1	160-bit
SHA-224	224-bit
SHA-256	256-bit
SHA-384	384-bit
SHA-512	512-bit

Mechanism

Salt-length

SHA-1

160-bit

SHA-224

224-bit

SHA-256

256-bit

SHA-384

384-bit

SHA-512

512-bit

¹² Wrap only.

¹³ The base key and the derived key are restricted to DES, DES3, CAST5 or Generic, though they may be of different types.

Vendor-defined mechanisms

The following vendor‑defined mechanisms are also available. The numeric values of vendor-defined key types and mechanisms can be found in the supplied pkcs11extra.h header file.

Some mechanisms may be restricted from use in Security Worlds conforming to FIPS 140-2 Level 3. See the User Guide for your HSM for more information.

CKM_WRAP_RSA_CRT_COMPONENTS

This wrapping mechanism uses a pMechanism→pParameter argument that is itself a CK_MECHANISM_PTR appropriate for the underlying encryption mechanism. The wrapping mechanism takes a pointer to a PKCS #11 template as its pWrappedKey argument.

The CK_ATTRIBUTE_PTR template is allocated by the calling application. The template is filled in by the calling application with the attribute types (CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT_2, CKA_COEFFICIENT), and the lengths of the value buffers, which are also allocated by the application. The pulWrappedKeyLen argument contains the length in bytes of the template, which is (5 * sizeof(CK_ATTRIBUTE_PTR)).

The usual method of calling C_WrapKey is with a NULL buffer to determine its output length. This is not available because C_WrapKey cannot specify the multiple levels of allocation required. If any part of this structure has an inappropriate size, the mechanism fails with a CKR_WRAPPED_KEY_LEN_RANGE error.

CKM_SEED_ECB_ENCRYPT_DATA & CKM_SEED_CBC_ENCRYPT_DATA

This mechanism derives a secret key by encrypting plain data with the specified secret base key. This mechanism takes as a parameter a CK_KEY_DERIVATION_STRING_DATA structure, which specifies the length and value of the data to be encrypted by using the base key to derive another key.

If no length or key type is provided in the template, the key produced by this mechanism is a generic secret key. Its length is equal to the length of the data.

If a length, but no key type, is provided in the template, the key produced by this mechanism is a generic secret key of the specified length.

If a key type, but no length, is provided in the template, the key type must have a well-defined length. If the length is well defined, the key produced by this mechanism is of the type specified in the template. If the length is not well defined, a CKR_TEMPLATE_INCOMPLETE error is returned.

If both a key type and a length are provided in the template, the length must be compatible with that key type, and CKR_TEMPLATE_INCONSISTENT is returned if it is not.

The key produced by the CKM_SEED_ECB_ENCRYPT_DATA or CKM_SEED_CBC_ENCRYPT_DATA mechanisms is of the specified type and length.

CKM_CAC_TK_DERIVATION

This mechanism uses C_GenerateKey to perform an Import operation using a Transport Key Component.

The mechanism accepts a template that contains three Transport Key Components (TKCs) with following attribute types:

CKA_TKC1
CKA_TKC2
CKA_TKC3.

These attributes are all in the CKA_VENDOR_DEFINED range.

Each TKC should be the same length as the key being created. TKCs used for DES, DES2, or DES3 keys must have odd parity. The mechanism checks for odd parity and returns CKR_ATTRIBUTE_VALUE_INVALID if it is not found.

The new key is constructed by an XOR of the three TKC components on the module.

Although using C_GenerateKey creates a key with a known value rather than generating a new one, it is used because C_CreateObject does not accept a mechanism parameter.

CKA_LOCAL, CKA_ALWAYS_SENSITIVE, and CKA_NEVER_EXTRACTABLE are set to FALSE, as they would for a key imported with C_CreateObject. This reflects the fact that the key was not generated locally.

An example of the use of CKM_CAC_TK_DERIVATION is shown here:

CK_OBJECT_CLASS class_secret = CKO_SECRET_KEY;
        CK_KEY_TYPE key_type_des2 = CKK_DES2;
        CK_MECHANISM mech = { CKM_CAC_TK_DERIVATION, NULL_PTR, 0 };
        CK_BYTE TKC1[16] = { ... };
        CK_BYTE TKC2[16] = { ... };
        CK_BYTE TKC3[16] = { ... };
        CK_OBJECT_HANDLE kHey;
        CK_ATTRIBUTE pTemplate[] = {
                { CKA_CLASS, &class_secret, sizeof(class_secret) },
                { CKA_KEY_TYPE, &key_type_des2, sizeof(key_type_des2) },
                { CKA_TKC1, TKC1, sizeof(TKC1) },
                { CKA_TKC2, TKC1, sizeof(TKC2) },
                { CKA_TKC3, TKC1, sizeof(TKC3) },
                { CKA_ENCRYPT, &true, sizeof(true) },
        ....
        };

        rv = C_GenerateKey(hSession, &mechanism, pTemplate,
                (sizeof(pTemplate)/sizeof((pTemplate)[0])), &hKey);

CKM_SHA_HMAC and CKM_SHA_HMAC_GENERAL

This version of the library supports the PKCS #11 standard mechanisms for SHA-1 and SHA-2 HMAC as defined in PKCS #11 standard version 2.30:

CKM_SHA_1_HMAC
CKM_SHA_1_HMAC_GENERAL
CKM_SHA224_HMAC
CKM_SHA224_HMAC_GENERAL
CKM_SHA256_HMAC
CKM_SHA256_HMAC_GENERAL
CKM_SHA384_HMAC
CKM_SHA384_HMAC_GENERAL
CKM_SHA512_HMAC
CKM_SHA512_HMAC_GENERAL

For security reasons, the Security World Software supports these mechanisms only with their own specific key type. Thus, you can only use an HMAC key with the HMAC algorithm and not with other algorithms.

The PKCS #11 standard does not provide an appropriate key type. Therefore, the vendor-defined key types CKK_SHA_1_HMAC, CKK_SHA224_HMAC, CKK_SHA256_HMAC, CKK_SHA384_HMAC, and CKK_SHA512_HMAC, are provided for use with these SHA-1 and SHA-2 HMAC mechanisms. To generate the key, use the appropriate vendor-defined key generation mechanism (which does not take any mechanism parameters):

CKM_NC_MD5_HMAC_KEY_GEN
CKM_NC_SHA_1_HMAC_KEY_GEN
CKM_NC_SHA224_HMAC_KEY_GEN
CKM_NC_SHA256_HMAC_KEY_GEN
CKM_NC_SHA384_HMAC_KEY_GEN
CKM_NC_SHA512_HMAC_KEY_GEN

CKM_NC_ECKDF_HYPERLEDGER

This version of the library supports the vendor-defined CKM_NC_ECKDF_HYPERLEDGER mechanism. This key derivation function is used in the user/client enrolment process of a hyperledger system to generate transaction certificates by using the enrolment certificate as one of the inputs to the key derivation.

The parameters for the mechanism are defined in the following structure:

typedef struct CK_ECKDF_HYPERLEDGERCLIENT_PARAMS {
    CK_OBJECT_HANDLE hKeyDF_Key;
    CK_MECHANISM_TYPE HMACMechType;
    CK_MECHANISM_TYPE TCertEncMechType;
    CK_ULONG ulEksize;
    CK_BYTE_PTR pEncTCertData;
    CK_ULONG ulEvsize;
    CK_ULONG ulEndian;
} CK_ECKDF_HYPERLEDGERCLIENT_PARAMS

Where:

hKeyDF_key is KeyDF_Key
HMACMechType is Hmac
TCertEncMechType is Decrypt_Mech
ulEksize is Eksize
pEncTCertData is a pointer to encrypted data containing TCertIndex together with padding and IV
ulEvsize is Evsize
ulEndian is Big_Endian

The function is then called as follows:

C_DeriveKey(
    hSession,
    &mechanism_hyperledger,
    EnrollPriv_Key,
    TCertPriv_Key_template,
    NUM(TCertPriv_Key_template,
    &TCertPriv_Key);

A Template_Key will be used to supply key attributes for the resulting derived key. The derived key can then be used in the normal way.

Derived keys can be exported and used outside the HSM only if the template key was created with attributes which allow export of its derived keys.

CKM_HAS160

This version of the library supports the vendor-defined CKM_HAS160 hash (digest) mechanism for use with the CKM_KCDSA mechanism. For more information, see Mechanisms for KISAAlgorithms.

CKM_PUBLIC_FROM_PRIVATE

CKM_PUBLIC_FROM_PRIVATE is a derive key mechanism that enables the creation of a corresponding public key from a private key. The mechanism also fills in the public parts of the private key, where this has not occurred.

CKM_PUBLIC_FROM_PRIVATE is an nShield specific nCore mechanism. The C_Derive function takes the object handle of the private key and the public key attribute template. The creation of the key is based on the template but also checked against the attributes of the private key to ensure the attributes are correct and match those of the corresponding key. If an operation that is not allowed or is not set by the private key is detected, then CKR_TEMPLATE_INCONSISTANT is returned.

Before you can use this mechanism, the HSM must already contain the private key. You must use C_CreateObject, C_UnWrapKey, or C_GenerateKeyPair to import or generate the private key.

If you use C_GenerateKeyPair, you always generate a public key at the same time as the private key. Some applications delete public keys once a certificate is imported, but in the case of both C_GenerateKeyPair and C_CreateObject you can use either the CKM_PUBLIC_FROM_PRIVATE mechanism or the C_GetAttributeValue to recreate a deleted public key.

CKM_NC_AES_CMAC

CKM_NC_AES_CMAC is based on the Mech_RijndaelCMAC nCore level mechanism, a message authentication code operation that is used with both C_Sign and C_SignUpdate, and the corresponding C_Verify and C_VerifyUpdate functions.

In a similar way to other AES MAC mechanisms, CKM_NC_AES_CMAC takes a plaintext type of any length of bytes, and returns a M_Mech_Generic128MAC_Cipher standard byte block. CKM_NC_AES_CMAC is a standard FIPS 140-2 Level 3 approved mechanism, and is only usable with CKK_AES key types.

CKM_NC_AES_CMAC has a CK_MAC_GENERAL_PARAMS which is the length of the MAC returned (sometimes called a tag length). If this is not specified, the signing operation fails with a return value of CKR_MECHANISM_PARAM_INVALID.

CKM_NC_AES_CMAC_KEY_DERIVATION and CKM_NC_AES_CMAC_KEY_DERIVATION_SCP03

This mechanism derives a secret key by validating parameters with the specified 128-bit, 192-bit, or 256-bit secret base AES key. This mechanism takes as a parameter a CK_NC_AES_CMAC_KEY_DERIVATION_PARAMS structure, which specifies the length and type of the resulting derived key.

CKM_NC_AES_CMAC_KEY_DERIVATION_SCP03 is a variant of CKM_NC_AES_CMAC_KEY_DERIVATION: it reorders the arguments in the CK_NC_AES_CMAC_KEY_DERIVATION_PARAMS according to payment specification SCP03, but is otherwise identical.

The standard key attribute behavior with sensitive and extractable attributes is applied to the resulting key as defined in PKCS #11 standard version 2.20 and later. The key type and template declaration is based on the PKCS #11 standard key declaration for derive key mechanisms.

If no length or key type is provided in the template, the key produced by this mechanism is a generic secret key. Its length is equal to the length of the data.

If a length, but no key type, is provided in the template, the key produced by this mechanism is a generic secret key of the specified length.

If both a key type and a length are provided in the template, the length must be compatible with that key type, and CKR_TEMPLATE_INCONSISTENT is returned if it is not.

The key produced by the CKM_NC_AES_CMAC_KEY_DERIVATION mechanism is of the specified type and length. If a DES, DES2, DES3, or CDMF key is derived with this mechanism, the parity bits of the key are set properly. If the requested type of key requires more bytes than are available by concatenating the original key values, an error is generated.

This mechanism has the following rules about key sensitivity and extractability:

Attribute	If the attributes for the original keys are…	The attribute for the derived key is…
CKA_SENSITIVE	CK_TRUE for either one	CK_TRUE
CKA_EXTRACTABLE	CK_FALSE for either one	CK_FALSE
CKA_ALWAYS_SENSITIVE	CK_TRUE for both	CK_TRUE
CKA_NEVER_EXTRACTABLE	CK_TRUE for both	CK_TRUE

Attribute

If the attributes for the original keys are…

The attribute for the derived key is…

CKA_SENSITIVE

CK_TRUE for either one

CK_TRUE

CKA_EXTRACTABLE

CK_FALSE for either one

CK_FALSE

CKA_ALWAYS_SENSITIVE

CK_TRUE for both

CK_TRUE

CKA_NEVER_EXTRACTABLE

CK_TRUE for both

CK_TRUE

CK_NC_AES_CMAC_KEY_DERIVATION_PARAMS

typedef struct CK_NC_AES_CMAC_KEY_DERIVATION_PARAMS {
    CK_ULONG ulContextLen;
    CK_BYTE_PTR pContext;
    CK_ULONG ulLabelLen;
    CK_BYTE_PTR pLabel;
  } CK_NC_AES_CMAC_KEY_DERIVATION_PARAMS;

The fields of the structure have the following meanings:

Argument Meaning

Argument	Meaning
ulContextLen	Context data: the length in bytes.
pContext	Some data info context data (bytes to be CMAC’d). `ulContextLen` must be zero if `pContext` is not provided. Having `pContext` as NULL will result in the same predictable key each time not additional data to add to the mix when carrying out the CMAC.
ulLabelLen	The length in bytes of the other party EC public key
pLabel	Key derivation label data: a pointer to the other label to identify new key. `ulLabelLen` must be zero if the `pLabel` is not provided.

ulContextLen

Context data: the length in bytes.

pContext

Some data info context data (bytes to be CMAC’d).

ulContextLen must be zero if pContext is not provided.

Having pContext as NULL will result in the same predictable key each time not additional data to add to the mix when carrying out the CMAC.

ulLabelLen

The length in bytes of the other party EC public key

pLabel

Key derivation label data: a pointer to the other label to identify new key. ulLabelLen must be zero if the pLabel is not provided.

CKM_COMPOSITE_EMV_T_ARQC, CKM_WATCHWORD_PIN1 and CKM_WATCHWORD_PIN2

These mechanisms allow the module to act as a SafeSign Cryptomodule (SSCM). To obtain support for your product, visit: nShield Support, https://nshieldsupport.entrust.com.

CKM_NC_ECIES

This version of the library supports the vendor defined CKM_NC_ECIES mechanism. This mechanism is used with C_WrapKey and C_UnwrapKey to wrap and unwrap symmetric keys using the Elliptic Curve Integrated Encryption Scheme (ECIES).

The parameters for the mechanism are defined in the following structure:

typedef struct CK_NC_ECIES_PARAMS {
       CK_MECHANISM_PTR <pAgreementMechanism>;
       CK_MECHANISM_PTR <pSymmetricMechanism>;
       CK_ULONG         <ulSymmetricKeyBitLen>;
       CK_MECHANISM_PTR <pMacMechanism>;
       CK_ULONG         <ulMacKeyBitLen>;
} CK_NC_ECIES_PARAMS;

Where:

<pAgreementMechanism> is the key agreement mechanism, which must be CKM_ECDH1_DERIVE or CKM_ECDH1_COFACTOR_DERIVE
<pSymmetricMechanism> is the confidentiality mechanism, currently only CKM_XOR_BASE_AND_DATA is supported
<ulSymmetricKeyBitLen> is the confidentiality key length (in bits) and must be a multiple of 8. For CKM_XOR_BASE_AND_DATA the key length is irrelevant and can be set to zero
<pMacMechanism> is the integrity mechanism, currently only CKM_SHA<n>_HMAC_GENERAL is supported and <n> can be _1, 224, 256, 384 or 512
<ulMacKeyBitLen> is the integrity key length (in bits) and must be a multiple of 8

The following example shows how to use CKM_NC_ECIES to wrap a symmetric key:

/* session represents an existing open session */
CK_SESSION_HANDLE session;

/* symmetric_key and wrapping_key represent existing keys. The code to import or
    generate them is not shown here. Note wrapping_key must be a public EC key
    with CKA_WRAP set to true */
CK_OBJECT_HANDLE symmetric_key;
CK_OBJECT_HANDLE wrapping_key;

CK_ECDH1_DERIVE_PARAMS ecdh1_params = { CKD_SHA256_KDF };
CK_MECHANISM agreement_mech = {
       CKM_ECDH1_DERIVE,
       &ecdh1_params,
       sizeof(CK_ECDH1_DERIVE_PARAMS)
};
CK_MECHANISM symmetric_mech = { CKM_XOR_BASE_AND_DATA };
CK_MAC_GENERAL_PARAMS mac_params = 16;
CK_MECHANISM mac_mech = {
       CKM_SHA256_HMAC_GENERAL,
       &mac_params,
       sizeof(CK_MAC_GENERAL_PARAMS)
};
CK_NC_ECIES_PARAMS ecies_params = {
       &agreement_mech,
       &symmetric_mech,
       0,
       &mac_mech,
       256
};
CK_MECHANISM ecies_mech = {
       CKM_NC_ECIES,
       &ecies_params,
       sizeof(CK_NC_ECIES_PARAMS)
};

/* Typical convention is to call C_WrapKey with the pWrappedKey parameter set to
   NULL_PTR to determine the required size of the buffer - see Section 5.2 of
   the PKCS#11 Base Specification - but for brevity we allocate a 1KB buffer */
CK_BYTE wrapped_key[1000] = { 0 };
CK_ULONG wrapped_len = sizeof(wrapped_key);
CK_RV rv = C_WrapKey(session, &ecies_mech, wrapping_key, symmetric_key,
                                               wrapped_key, &wrapped_len);

Mechanisms for KISAAlgorithms

If you are using version 1.20 or greater and you have enabled the KISAAlgorithms feature, you can use the following mechanisms through the standard PKCS #11 API calls.

KCDSA keys

The CKM_KCDSA mechanism is a plain general signing mechanism that allows you to use a CKK_KCDSA key with any length of plain text or pre-hashed message. It can be used with the standard single and multipart C_Sign and C_Verify update functions.

The CKM_KCDSA mechanism takes a CK_KCDSA_PARAMS structure that states which hashing mechanism to use and whether or not the hashing has already been performed:

typedef struct CK_KCDSA_PARAMS {
        CK_MECHANISM_PTR digestMechanism;
        CK_BBOOL dataIsHashed;
}

The following digest mechanisms are available for use with the digestMechanism:

CKM_SHA_1
CKM_HAS160
CKM_RIPEMD160

The dataIsHashed flag can be set to one of the following values:

1 when the message has been pre-hashed (pre-digested)
0 when the message is in plain text.

The CK_KCDSA_PARAMS structure is then passed in to the mechanism structure.

Pre-hashing

If you want to provide a pre-hashed message to the C_Sign() or C_Verify() functions using the CKM_KCDSA mechanism, the hash must be the value of h(z||m) where:

h is the hash function defined by the mechanism
z is the bottom 512 bits of the public key, with the most significant byte first
m is the message that is to be signed or verified.

The hash consists of the bottom 512 bits of the public key (most significant byte first), with the message added after this.

If the hash is not formatted as described when signing, then incorrect signatures are generated. If the hash is not formatted as described when verifying, then invalid signatures can be accepted and valid signatures can be rejected.

CKM_KCDSA_SHA1, CKM_KCDSA_HAS160, CKM_KCDSA_RIPEMD160

These older mechanisms sign and verify using a CKK_KCDSA key. They now work with the C_Sign and C_Update functions, though they do not take the CK_KCDSA_PARAMS structure or pre-hashed messages. These mechanisms can be used for single or multipart signing and are not restricted as to message size.

CKM_KCDSA_KEY_PAIR-GEN

This mechanism generates a CKK_KCDSA key pair similar to that of DSA. You can supply in the template a discrete log group that consists of the CKA_PRIME, CKA_SUBPRIME, and CKA_BASE attributes. In addition, you must supply CKA_PRIME_BITS, with a value between 1024 and 2048, and CKA_SUBPRIME_BITS, which must have a value of 160. If you supply CKA_PRIME_BITS and CKA_SUBPRIME_BITS without a discrete log group, the module generates the group. CKR_TEMPLATE_INCOMPLETE is returned if CKA_PRIME_BITS and CKA_SUBPRIME_BITS are not supplied.

CKA_PRIME_BITS must have the same length as the prime and CKA_SUBPRIME-BITS must have the same length as the subprime if the discrete log group is also supplied. If either are different, PKCS #11 returns CKR_TEMPLATE_INCONSISTENT.

You can use the C_GenerateKeyPair function to generate a key pair. If you supply one or more parts of the discrete log group in the template, the PKCS #11 library assumes that you want to supply a specific discrete log group. CKR_TEMPLATE_INCOMPLETE is returned if not all parts are supplied. If you want the module to calculate a discrete log group for you, ensure that there are no discrete log group attributes present in the template.

A CKK_KCDSA private key has two value attributes, CKA_PUBLIC_VALUE and CKA_PRIVATE_VALUE. This is in contrast to DSA keys, where the private key has only the attribute CKA_VALUE, the private value. The public key in each case contains only the public value.

The standard key-pair attributes common to all key pairs apply. Their values are the same as those for DSA pairs unless specified differently in this section.

CKM_KCDSA_PARAMETER_GEN

For information about DOMAIN Objects, read the PKCS #11 specification v2.11.

Use this mechanism to create a CKO_DOMAIN_PARAMETERS object. This is referred to as a KCDSAComm key in the nCore interface.

Use C_GenerateKey to generate a new discrete log group and initialization values. The initialization values consist of a counter (CKA_COUNTER) and a hash (CKA_SEED) that is the same length as CKA_PRIME_BITS, which must have a value of 160. The CKA_SEED must be the same size as CKA_SUBPRIME_BITS. If this not the case, the PKCS #11 library returns CKR_DOMAIN_PARAMS_INVALID.

Optionally, you can supply the initialization values. If you supply the initialization values with CKA_PRIME_BITS and CKA_SUBPRIME_BITS, you can reproduce a discrete log group generated elsewhere. This allows you to verify that the discrete log group used in key pairs is correct. If the initialization values are not present in the template, a new discrete log group and corresponding initialization values are generated. These initialization values can be used to reproduce the discrete log group that has just been generated. The newly generated discrete log group can then be used in a PKCS #11 template to generate a CKK_KCDSA key using C_Generate_Key_Pair. DOMAIN keys can also be imported using the C_CreateObject call.

SEED secret keys:

CKM_SEED_KEY_GEN

This mechanism generates a 128-bit SEED key. The standard secret key attributes are required, except that no length is required since this a fixed length key type similar to DES3. Normal return values apply when generating a CKK_SEED type key.

CKM_SEED_ECB CKM_SEED_CBC CKM_SEED_CBC_PAD

These mechanisms are the standard mechanisms to be used when encrypting and decrypting or wrapping with a CKK_SEED key. A CKK_SEED key can be used to wrap or unwrap both secret keys and private keys. A CKK_KCDSA key cannot be wrapped by any key type.

The CKM_SEED_ECB mechanism wraps only secret keys of exact multiples of the CKK_SEED block size (16) in ECB mode. The CKM_SEED_CBC_PAD key wraps the same keys in CBC mode.

The CKM_SEED_CBC_PAD key wraps keys of variable block size. It is the only mechanism available to wrap private keys.

A CKK_SEED key can be used to encrypt and decrypt with both single and multipart methods using the standard PKCS #11 API. The plain text size for multipart cryptographic function must be a multiple of the block size.

CKM_SEED_MAC CKM_SEED_MAC_GENERAL

These mechanisms perform both signing and verification. They can be used with both single and multipart signing or verification using the standard PKCS #11 API. Message size does not matter for either single or multipart signing and verification.

For information on the padding schemes used by these mechanisms, see Mechanisms.

CKM_HAS160

CKM_HAS160 is a basic hashing algorithm. The hashing is done on the host machine. This algorithm can be used by means of the standard digest function calls of the PKCS #11 API.

Attributes

The following sections describe how PCKS #11 attributes map to the Access Control List (ACL) given to the key by the nCore API. nCore API ACLs are described in the nCore API Documentation (supplied as HTML).

CKA_SENSITIVE

In a FIPS 140-2 Level 2 world, CKA_SENSITIVE=FALSE creates a key with an ACL that includes ExportAsPlain. Keys are exported using DeriveMech_EncryptMarshalled even in a FIPS 140-2 Level 2 world. The presence of the ExportAsPlain permission makes the status of the key clear when a FIPS 140-2 Level 2 ACL is viewed using GetACL.

CKA_SENSITIVE=FALSE always creates a key with an ACL that includes DeriveKey with DeriveRole_BaseKey and DeriveMech_EncryptMarshalled.

CKA_PRIVATE

If CKA_PRIVATE is set to TRUE, keys are protected by the logical token of the OCS. If it is set to FALSE, public keys are protected by a well-known module key, and other keys and objects are protected by the Security World module key.

You must set CKA_PRIVATE to:

FALSE for public keys
TRUE for non-extractable keys on card slots.

CKA_EXTRACTABLE

CKA_EXTRACTABLE creates a key with an ACL including DeriveKey permissions listed in the following table:

Key Type Role Mechanism

Key Type	Role	Mechanism
Secret key	`DeriveRole_BaseKey`	`DeriveMech_AESKeyWrap` `DeriveMech_RawEncrypt` `DeriveMech_RawEncryptZeroPad` `DeriveMech_ECIESKeyWrap`
Private key	`DeriveRole_BaseKey`	`DeriveMech_PKCS8Encrypt`

Secret key

DeriveRole_BaseKey

DeriveMech_AESKeyWrap

DeriveMech_RawEncrypt

DeriveMech_RawEncryptZeroPad

DeriveMech_ECIESKeyWrap

Private key

DeriveRole_BaseKey

DeriveMech_PKCS8Encrypt

CKA_ENCRYPT, CKA_DECRYPT, CKA_SIGN, CKA_VERIFY

These attributes create a key with ACL including Encrypt, Decrypt, Sign, or Verify permission.

CKA_WRAP, CKA_UNWRAP

CKA_WRAP creates a key with an ACL including the DeriveKey permissions listed in the following table:

Key Type Role Mechanism

Key Type	Role	Mechanism
Secret key	`DeriveRole_WrapKey`	`DeriveMech_PKCS8Encrypt`
Secret key (AES only)	`DeriveRole_WrapKey`	`DeriveMech_AESKeyWrap`
Secret key, public key (RSA only)	`DeriveRole_WrapKey`	`DeriveMech_RawEncrypt` `DeriveMech_RawEncryptZeroPad`
Public key (elliptic curve only)	`DeriveRole_WrapKey`	`DeriveMech_ECIESKeyWrap`

Secret key

DeriveRole_WrapKey

DeriveMech_PKCS8Encrypt

Secret key (AES only)

DeriveRole_WrapKey

DeriveMech_AESKeyWrap

Secret key, public key (RSA only)

DeriveRole_WrapKey

DeriveMech_RawEncrypt

DeriveMech_RawEncryptZeroPad

Public key (elliptic curve only)

DeriveRole_WrapKey

DeriveMech_ECIESKeyWrap

CKA_UNWRAP creates a key with an ACL including the DeriveKey permissions listed in the following table:

Key Type Role Mechanism

Key Type	Role	Mechanism
Secret key	`DeriveRole_WrapKey`	`DeriveMech_PKCS8Decrypt` `DeriveMech_PKCS8DecryptEx`
Secret key (AES only)	`DeriveRole_WrapKey`	`DeriveMech_AESKeyUnwrap`
Secret key, public key (RSA only)	`DeriveRole_WrapKey`	`DeriveMech_RawDecrypt` `DeriveMech_RawDecryptZeroPad`
Public key (elliptic curve only)	`DeriveRole_WrapKey`	`DeriveMech_ECIESKeyUnwrap`

Secret key

DeriveRole_WrapKey

DeriveMech_PKCS8Decrypt

DeriveMech_PKCS8DecryptEx

Secret key (AES only)

DeriveRole_WrapKey

DeriveMech_AESKeyUnwrap

Secret key, public key (RSA only)

DeriveRole_WrapKey

DeriveMech_RawDecrypt

DeriveMech_RawDecryptZeroPad

Public key (elliptic curve only)

DeriveRole_WrapKey

DeriveMech_ECIESKeyUnwrap

CKA_WRAP_TEMPLATE, CKA_UNWRAP_TEMPLATE

CKA_WRAP_TEMPLATE and CKA_UNWRAP_TEMPLATE guard against non-compliance of keys by specifying an attribute template.

The CKA_WRAP_TEMPLATE attribute applies to wrapping keys and specifies the attribute template to match against any of the keys wrapped by the wrapping key. Keys which do not match the attribute template will not be wrapped.

The CKA_UNWRAP_TEMPLATE attribute applies to wrapping keys and specifies the attribute template to apply to any of the keys which are unwrapped by the wrapping key. Keys will not be unwrapped if there is attribute conflict between the CKA_UNWRAP_TEMPLATE and any user supplied template (pTemplate).

Nested occurrences of CKA_WRAP_TEMPLATE or CKA_UNWRAP_TEMPLATE are not supported.

If CKA_MODIFIABLE or CKA_SENSITIVE are defined within the CKA_UNWRAP_TEMPLATE, the behavior is as follows:

CKA_MODIFIABLE (TRUE)
PKCS #11 Attribute Types	Unwrap Template Attribute	C_Unwrap pTemplate Attribute	Attribute Value Comparison	Allowed
All supported	Defined	Defined	Equal	Yes
	Defined	Defined	Not Equal	Yes
	Undefined	Defined	N/A	Yes
	Defined	Undefined	N/A	Yes

CKA_MODIFIABLE (FALSE)
PKCS #11 Attribute Types	Unwrap Template Attribute	C_Unwrap pTemplate Attribute	Attribute Value Comparison	Allowed
All supported	Defined	Defined	Equal	Yes
	Defined	Defined	Not Equal	No
	Undefined	Defined	N/A	Yes
	Defined	Undefined	N/A	Yes

CKA_SENSITIVE (TRUE)
PKCS #11 Attribute Types	C_Unwrap pTemplate Attribute	C_Unwrap pTemplate Attribute Value	Allowed
CKA_SENSITIVE	Defined	FALSE	No
CKA_EXTRACTABLE	Defined	FALSE	No

CKA_SENSITIVE (FALSE)
PKCS #11 Attribute Types	C_Unwrap pTemplate Attribute	C_Unwrap pTemplate Attribute Value	Allowed
CKA_SENSITIVE	Defined	TRUE	Yes
CKA_SENSITIVE	Defined	FALSE	Yes
CKA_EXTRACTABLE	Defined	TRUE	Yes
CKA_EXTRACTABLE	Defined	FALSE	Yes

CKA_SIGN_RECOVER

C_SignRecover checks CKA_SIGN_RECOVER but is otherwise identical to C_Sign. Setting CKA_SIGN_RECOVER creates a key with an ACL that includes Sign permission.

CKA_VERIFY_RECOVER

Setting CKA_VERIFY_RECOVER creates a public key with an ACL including Encrypt permission.

CKA_DERIVE

For Diffie-Hellman private keys, CKA_DERIVE creates a key with Decrypt permissions.

For secret keys, CKA_DERIVE creates a key with an ACL that includes DeriveRole_BaseKey with one of DeriveMech_DESsplitXOR, DeriveMech_DES2splitXOR, DeriveMech_DES3splitXOR, DeriveMech_RandsplitXOR, or DeriveMech_CASTsplitXOR as appropriate if the key is extractable, because this permission would effectively allow the key to be extracted. The ACL includes DeriveMech_RawEncrypt whether or not the key is extractable.

CKA_ALLOWED_MECHANISMS

CKA_ALLOWED_MECHANISMS is available as a full attribute array for all key types. The number of mechanisms in the array is the ulValueLen component of the attribute divided by the size of CK_MECHANISM_TYPE.

The CKA_ALLOWED_MECHANISMS attribute is set when generating, creating and unwrapping keys. You must set CKA_ALLOWED_MECHANISMS with the CKM_CONCATENATE_BASE_AND_KEY mechanism when generating or creating both of the keys that are used in the C_DeriveKey operation with the CKM_CONCATENATE_BASE_AND_KEY mechanism. If CKA_ALLOWED_MECHANISMS is not set at creation time then the correct ConcatenateBytes ACL is not set for the keys.

When CKM_CONCATENATE_BASE_AND_KEY is used with C_DeriveKey, CKA_ALLOWED_MECHANISMS is checked. If CKM_CONCATENATE_BASE_AND_KEY is not present, then an error occurs and a value of CKR_MECHANISM_INVALID is returned.

CKA_ALLOWED_MECHANISMS is an optional attribute and does not have to be set for any other operations. However, if CKA_ALLOWED_MECHANISMS is set, then the attribute is checked to see if the mechanism you want to use is in the list of allowed mechanisms. If the mechanism is not present, then an error occurs and a value of CKR_MECHANISM_INVALID is returned.

CKA_MODIFIABLE

CKA_MODIFIABLE only restricts access through the PKCS #11 API: all PKCS #11 keys have ACLs that include the ReduceACL permission.

CKA_TOKEN

Token objects are saved as key blobs. Session objects only ever exist on the module.

CKA_START_DATE, CKA_END_DATE

These attributes are ignored, and the PKCS #11 standard states that these attributes do not restrict key usage.

CKA_TRUSTED and CKA_WRAP_WITH_TRUSTED

CKA_TRUSTED and CKA_WRAP_WITH_TRUSTED guard against a key being wrapped and removed from the HSM by an untrusted wrapping key. A key with a CKA_WRAP_WITH_TRUSTED attribute can only be wrapped by a wrapping key with a CKA_TRUSTED attribute. A trusted key can only be given a CKA_TRUSTED attribute by the PKCS #11 Security officer.

The CKA_WRAP_WITH_TRUSTED attribute gives a key an ACL whose DeriveRole_BaseKey exists in a group protected by a certifier. The ACL therefore requires a certificate generated by the PKCS #11 Security Officer to be able to wrap the key.

The CKA_TRUSTED attribute stores on a wrapping key a certificate signed by the PKCS #11 Security Officer. This certificate can then be used to authenticate a wrapping operation.

CKA_TRUSTED can only be set if the session is logged in as CKU_SO, and the Security Officer’s token and key has been preloaded. If not, the operation will return CKR_USER_NOT_LOGGED_IN.

CKA_WRAP_WITH_TRUSTED does not require the Security Officer token and key to be preloaded, or to be logged in as CKU_SO, but it does require that the role exists. If the role does not exist, the operation returns CKR_USER_NOT_LOGGED_IN. When attributes have been set, the PKCS #11 Security Officer is not needed for C_WrapKey to perform a trusted key wrapping.

If the PKCS #11 Security Officer is deleted, keys with existing CKA_TRUSTED or CKA_WRAP_WITH_TRUSTED attributes continue to be valid. If the PKCS #11 Security Officer is recreated, any new keys that are given the CKA_TRUSTED attribute will not be trusted by existing keys with CKA_WRAP_WITH_TRUSTED, and vice versa.

A CKO_CERTIFICATE object can also be given a CKA_TRUSTED attribute, and also requires the PKCS #11 Security Officer to do so. This includes using ckcerttool with the -T option, which sets CKA_TRUSTED to true.

RSA key values

CKA_PRIVATE_EXPONENT is not used when importing an RSA private key using C_CreateObject. However, it must be in the template, since the PKCS #11 standard requires it. All the other values are required.

The nCore API allows use of a default public exponent, but the PKCS #11 standard requires CKA_PUBLIC_EXPONENT.

Except for very small keys, the nShield default is 65537, which as a PKCS #11 big integer is CK_BYTEpublic_exponent[ ] = { 1, 0, 1 };

DSA key values

If CKA_PRIME is 1024 bits or less, then the KeyType_DSAPrivate_GenParams_flags_Strict flag is used, because it enforces a 1024 bit limit.

The implementation allows larger values of CKA_PRIME, but in those cases the KeyType_DSAPrivate_GenParams_flags_Strict flag is not used.

Vendor specific error codes

Security World Software defines the following vendor specific error codes:

CKR_FIPS_TOKEN_NOT_PRESENT

This error code indicates that an Operator Card is required even though the card slot is not in use.

CKR_FIPS_MECHANISM_INVALID

This error code indicates that the current mechanism is not allowed in FIPS 140-2 Level 3 mode.

CKR_FIPS_FUNCTION_NOT_SUPPORTED

This error code indicates that the function is not supported in FIPS 140-2 Level 3 mode (although it is supported in FIPS 140-2 Level 2 mode).

Utilities

This section describes command-line utilities Entrust provides as aids to developers.

ckdes3gen

ckdes3.gen.exe [p|--pin-for-testing=<passphrase>] | [n|-nopin]

This utility is an example of Triple DES key generation using the nShield PKCS #11 library. The utility generates the DES3 key as a private object that can be used both to encrypt and decrypt.

By default, the utility prompts for a passphrase. You can supply a passphrase on the command line with the --pin-for-testing option, or suppress the passphrase request with the --nopin option. The passphrase is displayed in the clear on the command line, so this option is appropriate only for testing.

ckinfo

ckinfo.exe [r|--repeat-count=<COUNT>]

This utility displays C_GetInfo, C_GetSlotInfo and C_GetTokenInfo results. You can specify a number of repetitions of the command with --repeat-count=<COUNT>. The default is 1.

cklist

cklist.exe [-p|--pin-for-testing=<passphrase>] [-n|-nopin]

This utility lists some details of objects on all slots. It lists public and private objects if invoked with a passphrase argument and public objects only if invoked without a passphrase argument.

It does not output any potentially sensitive attributes, even if the object has CKA_SENSITIVE set to FALSE.

By default, the utility prompts for a passphrase. You can supply a passphrase on the command line with the --pin-for-testing option, or suppress the passphrase request with the --nopin option. The passphrase is displayed in the clear on the command line, so this option is appropriate only for testing.

ckmechinfo

ckmechinfo.exe

The utility displays C_GetMechanismInfo results for each mechanism returned by C_GetMechanismList.

ckrsagen

ckrsagen.exe [-p|--pin-for-testing=<passphrase>] | [-n|-nopin]

The ckrsagen utility is an example of RSA key pair generation using the nShield PKCS #11 library. This is intended as a programmer’s example only and not for general use. Use the key generation routines within your PKCS #11 application.

cksotool

cksotool.exe [-h] [--version] [-m MODULE] [-c | -p | -i | --delete]

The cksotool utility can be used to create and manage the PKCS #11 Security Officer (SO). The SO consists of a token and an RSA key, and is necessary to be able to perform any operations that require a Security Officer as defined by the PKCS #11 specification. The utility can be used to view the current state of the SO using the -i or --info option, which provides details of the existence and validity of the underlying token and key.

The key and softcard created by cksotool is for Entrust internal use inside the PKCS #11 library. It is not to be used directly in an application.

PKCS11

PKCS #11 developer libraries

PKCS #11 security assurance mechanism

PKCS #11 with load-sharing mode

Logging in

Session objects

Module failure

Compatibility

Restrictions on function calls in load-sharing mode

PKCS #11 with HSM Pool mode

Module failure

Module recovery

Restrictions on function calls in HSM Pool mode

PKCS #11 with key reloading

Usage under preload

Persistent preload files

Supported function calls

Retrying key reloads

Adding new HSMs

PKCS #11 without load-sharing mode or HSM Pool mode

K/N support for PKCS #11

Generating and deleting NVRAM-stored keys with PKCS #11

Generating NVRAM-stored keys

Deleting NVRAM-stored keys

PKCS #11 Security Officer

nShield-specific PKCS #11 API extensions

C_LoginBegin

C_LoginNext

C_LoginEnd

Compiling and linking

Windows

Linux

Objects

Certificate Objects and Data Objects

Key Objects

Card passphrases

Functions supported

General purpose functions

C_Initialize

Slot and token management functions

C_GetSlotList

C_InitToken

C_InitPIN

C_SetPIN

Standard session management functions

nShield session management functions

Object management functions

Encryption functions

Decryption functions

Message digesting functions

Signing and MACing functions

Functions for verifying signatures and MACs

Dual-purpose cryptographic functions

Key-management functions

Random number functions

Parallel function management functions

Callback functions

Mechanisms

Vendor-defined mechanisms

CKM_WRAP_RSA_CRT_COMPONENTS

CKM_SEED_ECB_ENCRYPT_DATA & CKM_SEED_CBC_ENCRYPT_DATA

CKM_CAC_TK_DERIVATION

CKM_SHA*_HMAC and CKM_SHA*_HMAC_GENERAL

CKM_NC_ECKDF_HYPERLEDGER

CKM_HAS160

CKM_PUBLIC_FROM_PRIVATE

CKM_NC_AES_CMAC

CKM_NC_AES_CMAC_KEY_DERIVATION and CKM_NC_AES_CMAC_KEY_DERIVATION_SCP03

CK_NC_AES_CMAC_KEY_DERIVATION_PARAMS

CKM_COMPOSITE_EMV_T_ARQC, CKM_WATCHWORD_PIN1 and CKM_WATCHWORD_PIN2

CKM_NC_ECIES

Mechanisms for KISAAlgorithms

KCDSA keys

Pre-hashing

CKM_KCDSA_SHA1, CKM_KCDSA_HAS160, CKM_KCDSA_RIPEMD160

CKM_KCDSA_KEY_PAIR-GEN

CKM_KCDSA_PARAMETER_GEN

SEED secret keys:

CKM_SEED_KEY_GEN

CKM_SEED_ECB CKM_SEED_CBC CKM_SEED_CBC_PAD

CKM_SHA_HMAC and CKM_SHA_HMAC_GENERAL