WLD System Setup

This section provides instructions on how to set up a system for Work Load Distribution. The example system contains 3 remote HSMs and 3 virtual WLD slots with SafeNet ProtectToolkit-C running on a Windows platform.

A diagram of the resulting configuration is shown in Example of WLD configuration. To any application or utility operating in WLD mode, the system of physical HSMs appears as a single virtual HSM that is accessible via virtual WLD slots. Any application or utility that accesses the system does so through the Cryptoki library. When an application or utility is configured to operate in WLD mode, the WLD virtual slots are the only slots made accessible by the Cryptoki Library. An application or utility configured to operate in WLD mode cannot access the HSM slots directly.

The arrows represent associations between the virtual WLD slots and the physical HSM slots in this configuration. For example, WLD Slot 11 is associated with User Slot 0 on HSM 0, User Slot 5 on HSM 1 and User Slot 9 on HSM 2.

Figure 1: Example of WLD configuration

WLD Slot	Associated HSM User Slots	Token Label
WLD Slot 11	Slot 0 (HSM 0) Slot 5 (HSM 1) Slot 9 (HSM 2)	WLD_Slot_11
WLD Slot 22	Slot 1 (HSM 0) Slot 4 (HSM 1) Slot 10 (HSM 2)	WLD_Slot_22
WLD Slot 33	Slot 2 (HSM 0)	WLD_Slot_33

WLD Slot

Associated HSM User Slots

Token Label

WLD Slot 11

Slot 0 (HSM 0)

Slot 5 (HSM 1)

Slot 9 (HSM 2)

WLD_Slot_11

WLD Slot 22

Slot 1 (HSM 0)

Slot 4 (HSM 1)

Slot 10 (HSM 2)

WLD_Slot_22

WLD Slot 33

Slot 2 (HSM 0)

WLD_Slot_33

As illustrated in Example of WLD configuration, each WLD slot shares the same token label (TL) as the HSM slots that are associated with it. For example, WLD Slot 22 shares the token label WLD_Slot_22 with its associated HSM User slots (1, 4, and 10).

You must know the Admin Token serial numbers (SN) when configuring the system for WLD operation. Each WLD slot must be configured with a unique serial number allocated by the user.

During configuration, the utilities must be able to access the HSM slots directly. They are initially configured to operate in NORMAL mode, as shown by the boxes at the bottom of the figure. After configuration, applications and utilities that need to access the system in WLD mode must be configured to operate in WLD mode.

Configuration

1.Establish Network Communication.

Set the environment variable ET_HSM_NETCLIENT_SERVERLIST with a list of the IP addresses of the HSMs in the order HSM0, HSM1, HSM2. IPv6 addresses must be enclosed in square brackets. See Specifying the Network Server(s) for more information.

2.Set the Library Mode to NORMAL.

The HSM slots must be accessible to set up the system, so the utilities which access them must operate in NORMAL mode. See Operation in WLD Mode for more on setting the Cryptoki Library to NORMAL mode.

3.Initialize Admin Tokens and Security Policy.

If an HSM has not been initialized, the Admin Token and Security Policy for each HSM must be configured. Refer to Initial Configuration for further details.

4.Create User Slots.

Create User slots for each HSM, as described below. Refer to Initial Configuration for further details.

User Slots	HSM
Slot 0 Slot 1 Slot 2	0
Slot 4 Slot 5 Slot 6	1
Slot 8 Slot 9 Slot 10	2

User Slots

HSM

Slot 0

Slot 1

Slot 2

Slot 4

Slot 5

Slot 6

Slot 8

Slot 9

Slot 10

5.Create Master Tokens.

In this example, the master tokens are created on HSM 0 and replicated to HSM 1 and HSM 2. The master tokens could be created on any HSM User slot that is associated with the WLD slot and then replicated to the other HSMs. As HSM 0 has slots associated with all the WLD slots used in this example, it was selected as the HSM to hold the master tokens.

Configure the tokens for each of the slots, according to the following table. Refer to Configuring WLD Slots for further details.

HSM 0 User Slot	Token Label
Slot 0	WLD_Slot_11
Slot 1	WLD_Slot_22
Slot 2	WLD_Slot_33

6.Create Keys, Certificates, Data, HW Objects on Master Tokens.

It is necessary to create any objects that are contained within the master tokens before the token is replicated. Refer to Token Replication for further details.

7.Establish Trust.

For token replication to be performed from the HSM holding the master tokens to another HSM, the HSMs must have a mutual trust relationship. Refer to Trust Management for further details.

As the master tokens are located on HSM 0 and are to be duplicated to HSM 1 and HSM 2, establish mutual trust relationships between

•HSM 0 and HSM 1

•HSM 0 and HSM 2

8.Replicate Tokens.

Once trust is established the tokens can be replicated. Refer to Token Replication for further details. Replicate the master tokens from HSM 0 to HSM 1 and HSM 2 as follows:

Master Token	Replication
WLD_Slot_11	Replicate token from User slot 0 (HSM 0) to User slot 5 (HSM 1)
WLD_Slot_11	Replicate token from User slot 0 (HSM 0) to User slot 9 (HSM 2)
WLD_Slot_22	Replicate token from User slot 1 (HSM 0) to User slot 4 (HSM 1)
WLD_Slot_22	Replicate token from User slot 1 (HSM 0) to User slot 10 (HSM 2)

9.Configure WLD Slots.

WLD slots are configured via environment variables at either the temporary, user or system level. Refer to Configuring WLD Slots for further details. In this example, WLD slots are configured at the system level:

a.Locate the registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\SafeNet\PTKC\WLD

b.Make the following assignments:

Variable	Assignment
ET_PTKC_WLD_SLOT_11	WLD_Slot_11,1011,WLD Slot: 11
ET_PTKC_WLD_SLOT_22	WLD_Slot_22,1022,WLD Slot: 22
ET_PTKC_WLD_SLOT_33	WLD_Slot_33,1033,WLD Slot :33

10.Set the Library Mode to WLD.

WLD mode is configured via an environment variable at either the temporary, user or system level. To any application or utility operating in WLD mode, the HSM system appears as a single virtual HSM with a collection of WLD virtual slots. The HSM physical slots are not accessible to applications or utilities operating in WLD mode (see Operation in WLD Mode).

11.Check the WLD Slot Configuration.

Run the ctkmu (WLD mode) utility to view the slots available on the system. Only the WLD virtual slots should be visible. Any HSM physical slot on the system which has not been associated to a WLD virtual slot will no longer be accessible.

Example:

ProtectToolkit C Key Management Utility 5.3.0

Copyright (c) Safenet, Inc. 2009-2016

Cryptoki Version  = 2.20

Manufacturer      = Safenet, Inc.

WLD_Slot_11                      (Slot 11)

WLD_Slot_22                      (Slot 22)

WLD_Slot_33                      (Slot 33)

Configuring WLD Slots

To operate SafeNet ProtectToolkit-C in WLD Mode, virtual WLD slots must be configured.

Configuration parameters for the WLD slots are specified by environment variables in the format ET_PTKC_WLD_SLOT_n. An environment variable must be configured for each WLD slot.

In the ET_PTKC_WLD_SLOT_n environment variable, n defines the Slot Number, an integer in the range 0 to 99. Slot Numbers allocated within an application must be unique.

The format of these variables is:

<WLDTokenLabel>[,[<WLDTokenSerial#>][,<WLDSlotDescription>]]

Where:

<WLDTokenLabel>	is mandatory. The PKCS #11 Token Label for this WLD Token identifies the HSM Tokens to be used for WLD. The <WLDTokenLabel> should be unique in the complete list of WLD Slot Configurations.
<WLDTokenSerial#>	is optional. You can assign any PKCS #11 Token Serial Number you wish to this WLD Token. The default value is the same as the value of n in the configuration variable name.
<WLDSlotDescription>	is optional. You can assign any PKCS #11 Slot Description you wish for this WLD Slot. The default value is “WLD Slot:n”, where n is the same as the value of n in the configuration variable name.

The example below shows a conceptual configuration for three virtual slots. The entire list of WLD Slots will be visible by any application that is using this WLD configuration.

UNIX

Under UNIX variants, the variable name and value are stored in the file et_ptkc in the directory /etc/default (for system configuration) and/or $HOME/.safenet (for user configuration).

Example:

To configure WLD slots at the system level:

>Open the file: /etc/default/et_ptkc

>Make the following entries:

ET_PTKC_WLD_SLOT_0=WLD Token 0,1002,PIN generation slot

ET_PTKC_WLD_SLOT_5=WLD Token 5

ET_PTKC_WLD_SLOT_6= WLD Token 6,,Password generation slot

NOTE For WLD Slot 5, SafeNet ProtectToolkit-C will assign the default PKCS #11 Token Serial Number of 5, and the PKCS #11 Slot Description “WLD Slot:5”. For WLD Slot 6, the default PKCS #11 Token Serial Number of 6 will be assigned.

Windows

Under Win32 and Win64, the variable name and value are stored in the HKLM (for system configuration) and/or HKCU (for user configuration) registry, in the key SOFTWARE\SafeNet\PTKC\WLD.

Example:

To configure WLD slots at the system level:

1.Locate the registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\SafeNet\PTKC\WLD

2.Assign the ET_PTKC_WLD_SLOT_n variables the values shown in the UNIX example above.