Creating an STC Link Between a Client and a Partition

Home >

Creating an STC Link Between a Client and a Partition

Note: Secure Trusted Channel requires firmware 6.22.0 or later.

If you require a higher level of security for your network links than is offered by NTL, such as in cloud environments, or in situations where message integrity is paramount, you can use Secure Trusted Channel (STC) to provide very secure client-partition links. STC offers the following features to ensure the security and integrity of your client-partition communications:

•Privacy of all communicated data through the use of symmetric encryption, so that only the end-points can read any sensitive data.

•Integrity of the communicated data through the use of message authentication codes, so that not eavesdropper could add, delete, modify or replay any command or response.

•Bi-directional authentication of both the HSM and the end-point, so that only authorized entities can establish an STC connection, and there can be no man-in-the-middle attack.

See "Secure Trusted Channel (STC) Network Links" on page 1 in the Administration Guide for more information.

Note: STC and NTL can co-exist on the same SafeNet Network HSM appliance, allowing you to configure some partitions to use STC, while other partitions use NTL. The client can also support both STC and NTLS links. However, all links from a specific client to a specific SafeNet Network HSM appliance can be either NTL or STC, but not both.

To use STC, you must enable the following policies:

•HSM policy 39: Allow Secure Trusted Channel. This policy enables STC on the HSM, so that you can configure the HSM such that some partitions to use STC, while other partitions use NTLS. This policy can only be set by the HSM SO.

•Partiton policy 37: Force Secure Trusted Channel. This policy forces the partition to use STC, and requires that HSM policy 39 is also set. For legacy partitions, this policy can be only be set by the HSM SO. For partitions with SO, this policy can only be set by the partition SO.

The procedure for creating an STC link between a client and a partition differs depending on whether the partition is a legacy partition or a partition with SO, as follows:

Legacy partitions	See Creating an STC Link to a Legacy Partition
Partitions with SO	See Creating an STC Link to a Partition With SO

Creating an STC Link to a Legacy Partition

The procedure for creating an STC link to a legacy partition consists of the following major steps:

1.Enable the STC policy on the HSM and partition.

2.Export the partition identity public key to a file on the appliance.

3.Create the client token and identity.

4.Exchange the partition and client identity public keys.

5.Register the client identity public key to the partition.

6.Register the partition identity public key with the client.

7.Enable and verify the STC link.

Step 1: Enable the STC policy on the HSM and partition

This step is performed by the HSM SO. For more information, including detailed procedures, examples, and a description of the impact of setting the policies, see "Enabling or Disabling STC on the HSM" on page 1, "Enabling or Disabling STC on a Partition" on page 1 and "Establishing and Configuring the STC Admin Channel on a SafeNet Network HSM Appliance" on page 1 in the Administration Guide.

1.Launch LunaSH and log in as the HSM SO.

2.Enter the following command to ensure that policy 39: Allow Secure Trusted Channel is enabled on the HSM:

hsm showpolicies

If it is not enabled, enter the following command to enable the policy:

hsm changePolicy -policy 39 -value 1

3.(Optional) Enable the STC admin channel to provide STC on all links (NTLS and STC) on the portion of the link from the appliance to the HSM, as described in "Establishing and Configuring the STC Admin Channel on a SafeNet Network HSM Appliance" on page 1 in the Administration Guide.

4.Enter the following command to ensure that policy 37: Force Secure Trusted Channel is enabled on the partition:

partition showpolicies -partititon <partition_name>

If it is not enabled, enter the following command to enable the policy:

partition changepolicy -partition <partition_name> -policy 37 -value 1

Step 2: Export the partition identity public key to a file on the appliance

This step is performed by the HSM SO. Exporting the partition identity public key creates the partition identity if it does not already exist. The public key is exported to a file named <partition_serial_number>.pid on the appliance.

1.Enter the following command to export the partition's public key to a file:

stc partition export -partition <partition_name>

For example:

lunash:>stc partition export -partition legacy_stc

Successfully exported partition identity for partition legacy_stc to file 359693009023.pid

Command Result : 0 (Success)

Step 3: Create the client token and identity

This step is performed by the root user on the SafeNet HSM client workstation, using LunaCM.

1.Open a SafeNet HSM client session:

a.Open a command prompt or terminal window.

b.Launch LunaCM:

Windows	C:\Program Files\SafeNet\LunaClient\bin\lunacm
Linux/AIX	/usr/safenet/lunaclient/data/bin/lunacm
Solaris/HP-UX	/opt/safenet/lunaclient/data/bin/lunacm

2.Initialize the STC client software token, or insert the STC client hardware token you have prepared for this client:

–If you are using an STC client software token, enter the following command to initialize the STC client token.

stc tokeninit -label <token_label>

For example:

lunacm:> stc tokeninit -label mySTCclientToken

Successfully initialized the client token.

–If you are using an STC client hardware token (SafeNet eToken 7300), insert the token into an available USB port. Before you can use a hardware token, the token must be initialized using the SafeNet Authentication Client on a Windows workstation, as described in "Using a Hard Token to Store the STC Client Identity" on page 1 in the Administration Guide.

In addition, you must also install the SafeNet Authentication Client software (8.3 or higher) on the client workstation and add the following line to the Secure Trusted Channel section of the crystoki.ini (Windows) or Chrystoki.conf (UNIX/Linux) file, to specify the path to the SafeNet Authentication Client eToken library:

Windows	ClientTokenLib=C:\Windows\System32\eToken.dll
Linux/UNIX	ClientTokenLib=<path_to_libeToken.so> For example, on CentOS, the path is /usr/lib/libeToken.so

3.Enter the following command to create a client identity on the token. The STC client identity public key is automatically exported to the <luna_client_root_dir>/data/client_identities directory:

stc identitycreate -label <client_identity>

For example:

lunacm:> stc identitycreate -label mySTCclientID

Client identity successfully created and exported to file /usr/safenet/lunaclient/data/client_identities/mySTCclientID

4.Exit LunaCM.

Step 4: Exchange the partition and client identity public keys

The STC identity public keys are exchanged as follows:

•the client identity public key is copied from the SafeNet HSM client data/client_identities directory to the SafeNet Network HSM appliance.

•the partition identity public key is copied from the appliance to the data/partition_identities directory on the SafeNet HSM client workstation.

Copying the public keys to or from the SafeNet Network HSM appliance is performed by the SafeNet Network HSM appliance administrator, using scp (UNIX/Linux) or pscp (Windows).

Copying the public keys to or from the SafeNet HSM client workstation is performed by the root user on the SafeNet HSM client workstation.

The following procedure assumes that you are able to perform both roles, that is, you can log in to the SafeNet HSM client workstation as root, and you possess the SafeNet Network HSM appliance admin password so that you can use scp/pscp to transfer files directly between the SafeNet HSM client workstation and the SafeNet Network HSM appliance.

If your IT and security policies require separation of roles, the keys can be exchanged manually, for example, using email with fingerprint verification, so that the root user on the SafeNet HSM client workstation is responsible for:

• providing the client identity public key to the SafeNet Network HSM appliance administrator.

•copying the partition identity public key to the data/partition_identities directory on the SafeNet HSM client workstation.

The SafeNet Network HSM appliance administrator is responsible for:

•using scp/pscp from a separate workstation to copy the client identity public key to the SafeNet Network HSM appliance.

• using scp/pscp from a separate workstation to copy the partition identity public key from the SafeNet Network HSM appliance and then providing it to the root user on the SafeNet HSM client workstation.

1.Log in to the SafeNet HSM client workstation as the root user.

2.Go to the SafeNet HSM client data/client_identities directory:

Windows	cd C:\Program Files\SafeNet\LunaClient\data\client_identities
Linux/AIX	cd /usr/safenet/lunaclient/data/client_identities
Solaris/HP-UX	cd /opt/safenet/lunaclient/data/client_identities

3.Export the client identity public key to the HSM appliance, using pscp (Windows) or scp (Linux/UNIX). You require the SafeNet Network HSM appliance admin password to complete this step:

Note: You must scp to the admin account on the HSM appliance, or the client public key will not register correctly. The file arriving at the appliance is automatically placed in the appropriate directory. Do not specify a target directory.

Windows

Syntax: pscp [options] <source_filename> <user>@<host>:[<target_filename>]

Example:To copy the client identity public key (mySTCclientID) to the myLunaSA appliance, keeping the same name:

pscp mySTCclientID admin@myLunaSA: 
admin@myLunaSA's password: ********  
mySTCclientID   | 1 kB |   1.1 kB/s | ETA: 00:00:00 | 100%

Linux/UNIX

Syntax:scp [options] <source_filename> <user>@<host>:[<target_filename>]

Example: To copy the client identity public key (mySTCclientID) to the SafeNet Network HSM appliance with IP 192.168.0.123, keeping the same name:

scp mySTCclientID admin@192.168.0.123: 
admin@192.168.0.123's password: ********  
mySTCclientID   | 1 kB |   1.1 kB/s | ETA: 00:00:00 | 100%

4.Go to the SafeNet HSM client data/partition_identities directory:

Windows	cd C:\Program Files\SafeNet\LunaClient\data\partition_identities
Linux/AIX	cd /usr/safenet/lunaclient/data/partition_identities
Solaris/HP-UX	cd /opt/safenet/lunaclient/data/partition_identities

5.Use pscp (Windows) or scp (Linux/UNIX) to import the partition public key from the SafeNet Network HSM appliance to the data/partition_identities directory on the SafeNet HSM client workstation. See Using the scp and pscp Utilities for details. You require the SafeNet Network HSM appliance admin password to complete this step:

Windows

Syntax: pscp [options] <user>@<host>:<source_filename> <target_filename>

Example:To copy the partition identity public key (359693009023.pid)from host myHSM to the current (.) directory, keeping the same name:

pscp admin@myHSM:359693009023.pid . 
admin@myHSM's password:

359693009023.pid     | 1 kB |   1.1 kB/s | ETA: 00:00:00 | 100%

Linux/UNIX

Syntax:scp [options] <user>@<host>:<source_filename> <target_filename>

Example: To copy the partition identity public key (359693009023.pid) from host IP 192.168.0.123 to the current (.) directory, keeping the same name:

                            scp admin@192.168.0.123:359693009023.pid . 
admin@192.168.0.123's password:   
359693009023.pid      | 1 kB |   1.1 kB/s | ETA: 00:00:00 | 100%

Step 5: Register the client identity public key to the partition

Note: Each client identity registered to a partition uses 2332 bytes of storage on the partition. Before registering a client identity to a partition, ensure that there is adequate free space.

This step is performed by the HSM SO. You can register multiple clients to a partition.

1.Launch LunaSH and log in as the HSM SO.

2.Enter the following command to register the client identity public key to the partition:

stc client register -partition <partition_name> -label <client_label> -file <client_public_key>

For example:

stc client register -partition mySTCpar -label myClient -file mySTCclientID

Step 6: Register the partition identity public key to the client

This step is performed by the root user on the SafeNet HSM client workstation.

1.Log in to the SafeNet HSM client workstation as the root user.

2.Open a SafeNet HSM client session:

a.Open a command prompt or terminal window.

b.Launch LunaCM:

Windows	C:\Program Files\SafeNet\LunaClient\bin\lunacm
Linux/AIX	/usr/safenet/lunaclient/data/bin/lunacm
Solaris/HP-UX	/opt/safenet/lunaclient/data/bin/lunacm

3.Enter the following command to register the partition identity public key to the client token:

stc partitionregister -file <partition_identity> [-label <partition_label>]

For example:

lunacm:> stc partitionregister -file /usr/safenet/lunaclient/partition_identities/359693009023.pid -label mySA_mySTCpartition

Step 7: Enable and verify the STC link

CAUTION: When you enable STC on the client, you must specify the SafeNet Network HSM appliance that hosts the partition you want to link to. This forces the client to use STC for all links to the specified SafeNet Network HSM appliance. Any existing NTLS links to the specified SafeNet Network HSM appliance will be terminated.

This step is performed by the root user on the SafeNet HSM client workstation.

1.Log in to the SafeNet HSM client workstation as the root user.

2.Open a SafeNet HSM client session:

a.Open a command prompt or terminal window.

b.Launch LunaCM:

Windows	C:\Program Files\SafeNet\LunaClient\bin\lunacm
Linux/AIX	/usr/safenet/lunaclient/data/bin/lunacm
Solaris/HP-UX	/opt/safenet/lunaclient/data/bin/lunacm

3.Enter the following command to determine the server ID of the SafeNet Network HSM appliance that hosts the partition:

clientconfig listservers

For example:

lunacm:> clientconfig listservers

Server ID   Server          Channel   HTL Required

0           192.168.0.123   STC       No

1           192.168.0.59    NTLS      No

4.Enter the following command to enable the STC link:

stc enable -id <server_id>

For example:

stc enable -id 0

You are about to enable STC to server mySA.

This will initiate an automatic restart of this application. All sessions

logged in through the application will be closed.

Are you sure you wish to continue?

Type 'proceed' to continue, or 'quit' to quit now -> proceed

Successfully enabled STC to connect to server mySA.

At this point, LunaCM restarts. If successful, the partition is listed in the list of available HSMs. You can use the stc identityshow command to list the partitions registered to the client token.

5.Enter the following command to verify the link. This command displays the status of the STC link for the current slot:

stc status

For example:

lunacm:> stc status

Enabled:        Yes

Status:         Connected

Channel ID:     2

Cipher Name:    AES 256 Bit with Cipher Block Chaining

HMAC Name:      HMAC with SHA 512 Bit

Creating an STC Link to a Partition With SO

Creating an STC link to a partition with SO is performed entirely by the root user on the SafeNet HSM client workstation, using LunaCM. The procedure consists of the following major steps:

1.Ensure that you have satisfied the prerequisite conditions.

2.Create the client token and identity.

3.Register the partition identity public key with the client.

4.Enable and verify the STC link.

5.Initialize the partition.

CAUTION: STC allows you to claim the partition as the holder of the partition public key, and creates a one-time temporary STC link to allow you to register the client to the partition. You must complete all of the steps in this procedure in a single LunaCM session. If you do not, the partition is locked, and will not be accessible. The only workaround is for the HSM SO to delete the partition, create a new partition, and provide you with new partition public key so that you can try again.

Step 1: Ensure that you have satisfied the prerequisite conditions

Before attempting to create an STC link to a partition with SO, ensure that you have satisfied the following prerequisites:

1.You have the STC partition identity public key for the partition. Before using the partition identity public key, it is recommended that you confirm its authenticity by verifying its hash. You can verify the partition identity public key hash after you register the partition identity public key to the client token, as outlined in the following procedure. The HSM SO can use the LunaSH command stc partition show -partition <partition_name> to display the partition identity public key hash and provide it to you with the partition identity public key.

2.Confirm with the HSM SO that policy 39: Allow Secure Trusted Channel is enabled on the HSM.

Note: This procedure automatically registers the client identity to the partition. Each client identity registered to a partition uses 2332 bytes of storage on the partition. Before enabling the STC link, ensure that there is adequate free space on the partition.

Step 2: Create the client token and identity

Note: This step is not required if you have already created a client token and identity. Verify using stc identityshow.

1.Open a SafeNet HSM client session:

a.Open a command prompt or terminal window.

b.Launch LunaCM:

Windows	C:\Program Files\SafeNet\LunaClient\bin\lunacm
Linux/AIX	/usr/safenet/lunaclient/data/bin/lunacm
Solaris/HP-UX	/opt/safenet/lunaclient/data/bin/lunacm

2.Initialize the STC client software token, or insert the STC client hardware token (SafeNet eToken 7300) you have prepared for this client:

–If you are using an STC client software token, enter the following command to initialize the STC client token.

stc tokeninit -label <token_label>

For example:

lunacm:> stc tokeninit -label mySTCclientToken

Successfully initialized the client token.

Windows	ClientTokenLib=C:\Windows\System32\eToken.dll
Linux/UNIX	ClientTokenLib=<path_to_libeToken.so> For example, on CentOS, the path is /usr/lib/libeToken.so

stc identitycreate -label <client_identity>

For example:

lunacm:> stc identitycreate -label mySTCclientID

Client identity successfully created and exported to file /usr/safenet/lunaclient/data/client_identities/mySTCclientID

Step 3: Register the partition identity public key to the client

1.Enter the following command to register the partition identity public key to the client token:

stc partitionregister -file <partition_identity> [-label <partition_label>]

For example:

lunacm:> stc partitionregister -file /usr/safenet/lunaclient/partition_identities/359693009023.pid -label mySA_mySTCpartition

2.If you were provided with the partition identity public key hash, enter the following command to verify that the hashes match:

stc identityshow

For example:

lunacm:> stc ids

Client Identity Name:		myclient

Public Key SHA1 Hash:		5f3395af2ae01ac25c1a27dc25

Partition Name	Partition Serial Number	 Partition Public Key SHA1 Hash

par_app3	124338921974	         23159590be9b57fd0c9d8a84beeed04d4279c01c

par_app47	152943202231	         de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3

par_app12	150253010085	         2fd4e1c67a2d28fced849ee1bb76e7391b93eb12

If the hashes do not match, enter the following command to deregister the partition identity public key, and contact your HSM SO.

stc partitionderegister -serial <partition_serial_number>

Step 4: Enable and verify the STC link

1.Enter the following command to determine the server ID of the SafeNet Network HSM appliance that hosts the partition:

clientconfig listservers

For example:

lunacm:> clientconfig listservers

Server ID   Server          Channel   HTL Required

0           192.168.0.123   STC       No

1           192.168.0.59    NTLS      No

2.Enter the following command to enable the STC link:

stc enable -id <server_id>

For example:

lunacm:> stc enable -id 0

You are about to enable STC to server mySA.

This will initiate an automatic restart of this application. All sessions

logged in through the application will be closed.

Are you sure you wish to continue?

Type 'proceed' to continue, or 'quit' to quit now -> proceed

Successfully enabled STC to connect to server mySA.

At this point, LunaCM restarts. If successful, the partition is listed in the list of available HSMs. The slot for the partition is easily identified because it does not have a label, since it is not yet initialized. In the following example, the uninitialized PPSO partition is in slot 1:

Available HSMs:

Slot Id ->              0

Label ->                stc_legacy

Serial Number ->        359693009024

Model ->                K6 Base

Firmware Version ->     6.22.0

Configuration ->        Luna User Partition, No SO (PW) Signing With Cloning Mode

Slot Description ->     Net Token Slot

Slot Id ->              1

Label ->

Serial Number ->        359693009027

Model ->                K6 Base

Firmware Version ->     6.22.0

Configuration ->        Luna User Partition, No SO (PW) Signing With Cloning Mode

Slot Description ->     Net Token Slot

3.Enter the following command to set the current slot to the slot containing the new partition:

slot set -slot <slot>

For example:

lunacm:> slot set -slot 1

4.Enter the following command to verify the link:

stc status

For example:

lunacm:> stc status

Enabled:        Yes

Status:         Connected

Channel ID:     2

Cipher Name:    AES 256 Bit with Cipher Block Chaining

HMAC Name:      HMAC with SHA 512 Bit

Step 5: Initialize the partition

When you initialize the partition, the following actions are performed automatically:

•the client identity public key is registered to the partition.

•partition policy 37: Force Secure Trusted Channel is enabled on the partition.

1.Set the current slot to the slot containing the uninitialized (unlabelled) partition.

2.Enter the following command to initialize the partition. On a password-authenticated HSM, you are prompted to specify the partition SO password and domain you want to use for the partition. On a PED-authenticated HSM, you are prompted to attend to the PED to imprint (or provide) the partition SO PED key and domain PED key:

partition initialize -label <partition_label>

For example:

lunacm:> par init -label stc_ppso

You are about to initialize the partition.

All contents of the partition will be destroyed.

Are you sure you wish to continue?

Type 'proceed' to continue, or 'quit' to quit now ->proceed

Enter password for Partition SO: ********

Re-enter password for Partition SO: ********

Option -domain was not specified.  It is required.

Enter the domain name: *******

Re-enter the domain name: *******

Command Result : No Error

The slot now shows the label, indicating that it is initialized:

lunacm:> slot list

Slot Id ->              0

Label ->                stc_legacy

Serial Number ->        359693009024

Model ->                K6 Base

Firmware Version ->     6.22.0

Configuration ->        Luna User Partition, No SO (PW) Signing With Cloning Mode

Slot Description ->     Net Token Slot

Slot Id ->              1

Label ->                stc_ppso

Serial Number ->        359693009027

Model ->                K6 Base

Firmware Version ->     6.22.0

Configuration ->        Luna User Partition, No SO (PW) Signing With Cloning Mode

Slot Description ->     Net Token Slot

You can now create the Crypto Officer and Crypto User roles on the partition. See Configure PPSO Application Partitions.