External Key Storage Configuration

There are a number of files named cryptoki.dll provided as part of the SafeNet ProtectToolkit-C installation. This design ensures that PKCS #11 applications always link to a library called cryptoki.dll. The table below gives the location of cryptoki.dll files and their purpose. The ID field identifies the Cryptoki library and is used in discussions that follow.

Path	Purpose	ID
C:\Program Files\SafeNet\Protect Toolkit 5\Protect Toolkit C RT	Cryptoki library used for runtime applications	1
C:\Program Files\SafeNet\Protect Toolkit 5\ProtectToolkit C RT\extToken	ExtToken library used for runtime applications	2
C:\Program Files\SafeNet\Protect Toolkit 5\ProtectToolkit C SDK\bin\logger	Logger library used during application development	3
C:\Program Files\SafeNet\Protect Toolkit 5\ProtectToolkit C SDK\bin\hsm	Cryptoki library used during application development when communicating to HSMs	4
C:\Program Files\SafeNet\Protect Toolkit 5\ProtectToolkit C SDK\bin\ExtToken	ExtToken library used for application development	5
C:\Program Files\SafeNet\Protect Toolkit 5\ProtectToolkit C SDK\bin\sw	Cryptoki library used during application development in software-only mode	6

Configuring External Key Storage

As both the ExtToken library and a Cryptoki library are named cryptoki.dll and used in a configuration that requires external key storage, environment variables indicate which library is linked to which software component. As indicated in External Key Storage Model, PKCS#11 applications link to the ExtToken library, which in turn links to a Cryptoki library. The following subsections detail how this can be achieved:

>To configure External Key Storage for application development

>To configure External Key Storage for Runtime operation

NOTE The following processes should only be followed if the ExtToken library is to be used. To switch between one of the hardware modes and software-only mode, use the setmode utility. See Changing the Cryptoki Provider for details.

To configure External Key Storage for application development

1.Locate the current cryptoki.dll in use.

The current Cryptoki library in use is determined by the Path environment variable. The first folder named in the Path environment variable that contains a cryptoki.dll file indicates the path to the current Cryptoki library. Refer to the table above for folder locations.

NOTE Record for use in step 3 the path of the folder containing the current cryptoki.dll.

2.In the Path environment variable, insert the path to the ExtToken library, so that this folder appears before any other folders containing cryptoki.dll files. This is typically C:\Program Files\SafeNet\Protect Toolkit 5\ProtectToolkit C SDK\bin\ExtToken

3.Configure the ET_PTKC_EXTTOKEN_PKCS11LIB environment variable.

ET_PTKC_EXTTOKEN_PKCS11LIB is the fully qualified file path to the original cryptoki.dll located in step 1.

Typically this should be achieved by:

a.Creating or editing the registry key

HLKM (or HKCU)\SOFTWARE\SafeNet\PTKC\EXTTOKEN.

b.Creating a string value named ET_PTKC_EXTTOKEN_PKCS11LIB.

c. Setting the string to the fully qualified path of the original cryptoki.dll.

To specify the SafeNet ProtectToolkit-C SDK (PCI and network modes) Cryptoki library (Id 4), typically, ET_PTKC_EXTTOKEN_PKCS11LIB should be set to

C:\Program Files\SafeNet\Protect Toolkit 5\ProtectToolkit C SDK\bin\hsm.

4.Configure the ET_PTKC_EXTTOKEN_PATH environment variable in the registry key HLKM(or HKCU)\SOFTWARE\SafeNet\PTKC\EXTTOKEN. ET_PTKC_EXTTOKEN_PATH is the fully qualified directory path that determines where ExtToken stores its data files. These data files will contain the encrypted key material. The default value is C:\ETExtToken.

5.Configure the ET_PTKC_EXTTOKEN_MAXLOADED environment variable in the registry key HLKM(or HKCU)\SOFTWARE\SafeNet\PTKC\EXTTOKEN. ET_PTKC_EXTTOKEN_MAXLOADED is the maximum number of objects which will be loaded to the underlying token at one time. If this limit is reached, then the least used object is unloaded from the underlying token. The default value is 100.

To check the configuration

The steps listed previously should result in a configuration where the utilities provided in the SDK folders provide a view of the HSM deploying the ExtToken functionality. These utilities should be utilized for the management of external key storage.

In this configuration, the utilities installed under the Runtime folder do not utilize the ExtToken library and can be used to verify correct operation.

1.Open a command prompt in the SDK bin folder. This should typically be C:\Program Files\SafeNet\Protect Toolkit 5\ProtectToolkit C SDK\bin\hsm. This Window is referred to as Command Prompt(1) in later steps.

2.Open a command prompt in the Runtime folder. This should typically be C:\Program Files\SafeNet\Protect Toolkit 5\Protect Toolkit C RT. This Window is referred to as Command Prompt(2) in later steps.

3.At Command Prompt(1) enter the command ctkmu l –s0.

This command is generally utilized to display a list of the objects contained in slot 0. When used with the ExtToken functionality, this command additionally serves to initialize the mechanism that provides the external key storage functionality in the HSM. In a HSM where the ExtToken mechanism has not been initialized, this results in the creation of a number of objects on the HSM and the creation of the secure storage files on the Host.

4.Verify the creation of ExtToken mechanism on the HSM.

5.At Command Prompt(2) enter the command ctkmu l –s0.

Three additional objects should have been created with the label ExtToken. The first object is a Data object containing information relating to the configuration of ExtToken. Two secret keys are created; one key is for private objects and the other key is for public objects. These keys are only visible when the utility utilizes the Cryptoki Library. When the utility utilizes the ExtToken Library only the externally stored keys are visible.

6. Verify the creation of the Storage Files on the Host computer.

The ET_PTKC_EXTTOKEN_PATH determines the location of the storage files. This is typically C:\ETExtToken. Refer to step 4 above. Check that the folder has been created and contains an .ord file and an .ort file.

To configure External Key Storage for Runtime operation

In the standard installation folder hierarchy for the runtime software components, the utilities and the cryptoki.dll file are located in the same folder.

If a cryptoki.dll file is located in the same directory as the utilities, the utilities make use of this library, otherwise a utility located via the path environment variable is used. As this configuration requires the utilities to use the ExtToken library (Id 2) the Runtime Cryptoki library (Id 1) must be removed from the folder containing the utilities.

1.Move the Runtime Cryptoki Library from its current location (typically in folder C:\Program Files\SafeNet\Protect Toolkit 5\Protect Toolkit C RT (Id 1)) into a new sub-folder in this folder called hsm (typically C:\Program Files\SafeNet\Protect Toolkit 5\Protect Toolkit C RT\hsm).

3.Configure the ET_PTKC_EXTTOKEN_PKCS11LIB environment variable. ET_PTKC_EXTTOKEN_PKCS11LIB is the fully qualified file path to the original cryptoki.dll located in step 1. Typically this should be achieved by creating or editing the registry key HLKM(or HKCU)\SOFTWARE\SafeNet\PTKC\EXTTOKEN, creating a string value named ET_PTKC_EXTTOKEN_PKCS11LIB and setting it to the fully qualified path to the original cryptoki.dll (typically C:\Program Files\SafeNet\Protect Toolkit 5\Protect Toolkit C RT\hsm\cryptoki.dll).

To check the configuration

1.Open a command prompt in the Runtime folder. This should typically be C:\Program Files\SafeNet\Protect Toolkit 5\Protect Toolkit C RT.

2.Set the ET_PTKC_EXTTOKEN_PKCS11LIB environment variable to point to the directory containing the original cryptoki.dll file (C:\Program Files\SafeNet\Protect Toolkit 5\Protect Toolkit C RT\hsm in this example).

3.Enter the command ctkmu l –s0. This command is generally used to display a list of the objects contained in slot 0. When used with the ExtToken functionality, this command additionally serves to initialize the mechanism that provides the external key storage functionality in the HSM. In a HSM where the ExtToken mechanism has not been initialized, this results in the creation of a number of objects on the HSM and the creation of the secure storage files on the Host.

4.Verify the creation of the Storage Files on the Host computer. The ET_PTKC_EXTTOKEN_PATH determines the location of the storage files. This is typically C:\ETExtToken. Refer to step 4 above. Check that the folder has been created and contains an .ord file and an .ort file.