External Key Storage Configuration
There are a number of files named cryptoki.dll provided as part of the 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. For more information about configuring this environment variable, refer to External Key Storage Configuration Items.
4.Configure the ET_PTKC_EXTTOKEN_PATH environment variable. For more information about configuring this environment variable, refer to External Key Storage Configuration Items.
5.Configure the ET_PTKC_EXTTOKEN_MAXLOADED environment variable. For more information about configuring this environment variable, refer to External Key Storage Configuration Items.
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 by checking if the folder has been created and contains an .ord file and an .ort file.
The ET_PTKC_EXTTOKEN_PATH determines the location of the storage files. For more information about this environment variable, refer to External Key Storage Configuration Items.
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).
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\Protect Toolkit C RT\ExtToken.
3.Configure the ET_PTKC_EXTTOKEN_PKCS11LIB environment variable. For more information about configuring this environment variable, refer to External Key Storage Configuration Items.
4.Configure the ET_PTKC_EXTTOKEN_PATH environment variable. For more information about configuring this environment variable, refer to External Key Storage Configuration Items.
5.Configure the ET_PTKC_EXTTOKEN_MAXLOADED environment variable. . For more information about configuring this environment variable, refer to External Key Storage Configuration Items.
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). For more information about configuring this environment variable, refer to External Key Storage Configuration Items.
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 by checking if the folder has been created and contains an .ord file and an .ort file.
The ET_PTKC_EXTTOKEN_PATH determines the location of the storage files. For more information about this environment variable, refer to External Key Storage Configuration Items.
