.. _setting_up_lunasa: 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. 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`. 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 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 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: 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). 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. 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 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. Partition policies .................. Partition policies can be viewed on the Luna SA using the command:: lunash:> partition showPolicies -partition yourPartition 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 .. _register_hsm_client: 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 certificates 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. 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 Create AES Keys --------------- You can create AES keys on the HSM using the security module:: python linotp/lib/security/pkcs11.py