8.3. Setting up SafeNet LunaSA

Warning

This documentation does not replace the SafeNet LunaSA documentation. The HSM is a sophisticated device - you should consult the manual and know what you are doing.

8.3.1. Requirements

You need to install the following software packages on the LinOTP server that were delivered with your HSM:

• ctp-4.5.0
• libcryptoki-4.5.0
• vtl-4.5.0

The components are installed to /usr/lunasa. The executables are located at /usr/lunasa/bin.

8.3.2. Network settings

Note

For connecting to the Luna SA you need to connect the Luna SA appliance with the client computer via a null modem cable with the following settings: Serial port baud rate: 115200 N,8,1 (no parity, 8 data-bits, one stop-bit) VT-100 terminal emulation. Hardware flow

Alternatively the HSM is accessible via IP 192.168.0.1. After the first login with the username admin and the password chrysalis the password is requested to be changed. Furthermore the time needs to be set and the network should be configured:

# setting time zone
lunash:> sysconf timezone -set Europe/Berlin
# setting time
lunash:> sysconf -time 12:55 20071223
# setting hostname
lunash:> net hostname hsm1
# set domain name
lunash:> net domain example.com
# set multiple nameservers
lunash:> net dns -nameserver 172.16.16.6
lunash:> net dns -nameserver 172.16.16.7
# set multiple search domains
lunash:> net dns -search example.com
# set eth0. (eth1 may also be set)
   lunash:> net interface -static -device eth0 \
   -ip 172.16.16.102 -netmask 255.255.255.224 \
   -gateway 172.16.1
# control the settings
lunash:> net show

Now the LunaSA can be contacted via ssh. When the network connection is working correctly an ntp service can be set up. Setting up the domain controller in forest root as NTP servers:

lunash:> sysconf ntp -addserver 172.16.16.6

8.3.3. LunaSA server certificate

Note

For communication the LunaSA generates a certificate. For correct generation the LunaSA needs to be inserted in the DNS servers or in /etc/hosts.

When the DNS server resolve the hsm1 correctly the server certificate can be generated:

lunash:> sysconf regenCert
CAUTION: Current Server Certificate and Private Key will be
overwritten. All clients will have to add the server
again with new certificate.
Type ‘proceed’ to generate cert or ‘quit’ to cancel
> proceed

To be able to use the LunaSA via network, the trusted interface has to be defined:

lunash:>ntls bind eth0

8.3.4. Initialization of HSM

To be able to initialize the HSM the Luna PED needs to be connected to the LunaSA appliance and you need to got a set of PED Keys. The LunaSA is configured via the hsm init command. Most of the parameters for this command are entered via the Luna PED.:

lunash:> hsm init -label hsm1

Note

You should stick to the web based documentation closely, since this is a sensitive process.

Roughly after having issued the hsm init command the process is as follows:

8.3.4.1. Create HSM Admin PED Key

• Insert the blue PED key. This will be the ‘’HSM Admin PED Key’‘.
• As the fresh key is blank, a new PED PIN needs to be chosen.
• by Copy this PED Key backup copies of the PED key can be generated.
• Login as HSM Admin (Security Officer /SO).

8.3.4.2. Create Domain PED Key

• Insert a second PED key. This will be the ‘’Domain PED Key’‘.
• If this is a fresh key, a new PED PIN should also be set.
• Backups can be generated.

The initialization of the HSM has finished now. Copies of the PED Keys can also be made later.

8.3.4.3. HSM security polices

Using the command:

hsm showPol -c

you can display the policies:

Description                              Value        Code      Destructive
===========                              =====        ====      ===========
Allow cloning                            On           7         Yes
Allow non-FIPS algorithms                On           12        Yes
Allow MofN auto-activation               On           13        No
SO can reset partition PIN               On           15        Yes
Allow network replication                On           16        No
Allow Remote Authentication              On           20        Yes
Force user PIN change after set/reset    Off          21        No

For performing Backups the policy Allow cloning must be ON. For a redundant HA setup the policies Allow cloning and Allow network replication must be ON.

To switch a policy to ON use the command:

hsm changePol -p 7 -v 1

8.3.4.4. Create HSM Partitions

The LunaSA HSM can be partitioned that way, that each LinOTP is using an own partition of the HSM. To create a new partition on the HSM you must connect the Luna PED and logon as HSM admin issuing the command:

lunash:> hsm login

and inserting the blue HSM Admin PED Key.

A new partition is created issuing the command:

lunash:> partition create -name yourPartition

A black Partition Owner PED Key is generated. A PIN for the black PED Key needs to be set. When asked Are you duplicating this PED Key Y/N? backups of the black PED Key may be generated.

The Luna PED will now display the Password that clients (the LinOTP server) will use to authenticate to this partition. As this password will never show again anywhere else, it needs to be recorded/remembered:

Login secret value
btqx-EFGH-3456-7/K9
Please write it down.
(Press ENTER)

After displaying the client password the creation of the partition has finished.

If you have more partitions, create all other partitions with new black partition owner keys.

For each partition a separate black Partition Owner PED Key should be used. Otherwise the LunaSA will create a so called Group PED Key.

Note

When creating Group PED Keys the access rights to the HSM of the LinOTP servers can not be separated! It is recommended to use a separate PED Key for each partition.

8.3.4.5. Partition policies

Partition policies can be viewed on the Luna SA using the command:

lunash:> partition showPolicies -partition yourPartition

8.3.4.6. Activate Partitions

In order for an application to access the partition without the black partition owner key plugged in, the Partition needs to be activated. Therefor the Policy Allow activation needs to be set to 1:

lunash:> partition changePolicy -partition
         yourPartition -policy 22 -value 1

For setting the partition policy you need to have the blue SO PED key. Afterwards the partition can be activated:

lunash:> partition activate -partition partitionPolicyCA

When activating the partition you need to enter the client password that was generated when the partition was initialized. For activating the partition you need to have the Partition Owner PED key.

If the HSM lost power and you start the HSM again, the partition needs to be activated again. To avoid this, you can turn the Autoactivation policy on:

lunash:> partition changePolicy -partition
         yourPartition -policy 23 -value 1

8.3.5. Setting up HSM clients and assigning clients to HSM partitions

A LinOTP server talking to the HSM is called a HSM client. The connection is encrypted and authenticated via certifcates on both sides. The certificate of the LunaSA was already generated. This server certificate needs to be transferred to each LinOTP server.

Copy the server certificate to each LinOTP by issuing the command:

./ctp admin@hsm1:server.pem .

You need to add the HSM server on the client side:

./vtl addServer -n hsm1 -c server.pem

Now the client needs to get a client certificate created:

./vtl createCert -n linotp

Copy the client certificate to the LunaSA:

./ctp cert/client/linotp.pem admin@hsm1:

Now the client needs to be registered on the LunaSA and be assigned to a partition. Therefore on the LunaSA the admin must issue the following commands:

# register the client
lunash:> client register -client linotp -hostname linotp
# assign a client to partition
lunash:> client assignPartition -client linotp -partition yourPartition

Verify the working connection by:

./vtl verify

You should see a list with the available slots. You also need the slot number to configure later in LinOTP.

8.3.6. Troubleshooting

The names must resolve successfully. Try to ping the HSM from the LinOTP server by name and the LinOTP server from the HSM:

lunash:> net ping linotp

It could be that the ntls service needs to be restarted:

lunash:> service restart ntls

8.4. Create AES Keys

You can create AES keys on the HSM using the security module:

python linotpee/lib/security/pkcs11.py