.. _defining_lunasa:

Defining SafeNet LunaSA
-----------------------

.. note:: Please also refer to the original Luna SA HTML documentation for more detailed information!

LinOTP is well tested with the SafeNet LunaSA 4.5 PED.

To have the encryption handled by the LunaSA a PKCS11 security module is used. 

You need to define it in the `/etc/linotp2/linotp.ini` like this::

   linotpSecurity.lunasa.module = linotp.lib.security.pkcs11.Pkcs11SecurityModule
   
   linotpActiveSecurityModule = lunasa

   linotpSecurity.lunasa.library = libCryptoki2_64.so
   linotpSecurity.lunasa.configLabel =config
   linotpSecurity.lunasa.valueLabel =value
   linotpSecurity.lunasa.tokenLabel =token
   linotpSecurity.lunasa.defaultLabel =token
   linotpSecurity.lunasa.password = /RMF-At5F-p6XJ-HR64
   linotpSecurity.lunasa.slotid = 1

The parameters "library", "configLabel", "valueLabel", "tokenLabel", "defaultLabel", 
"password" and "slotid" are module dependent parameters. Other future modules may have other
parameters.



``library``
   This is the PKCS11 library. In case of the LunaSA this is the `libCryptoki2_4.so.`
  
``password``
   The password of the PKCS11 slot aka. the smartcard PIN.
   
``slotid``
   This is the slot where the AES keys are located. In case of the LunaSA this 
   is the partition. You can check for the slot number by issuing the command 
   ``vtl verify``.
   
``configHandle``, ``valueHandle``, ``tokenHandle``, ``defaultHandle``
   These are the handles of the AES key objects in the slot. 
   `configHandle`, `valueHandle` and  `tokenHandle` are used. 
   If on of the parameters is missing, the
   `defaultHandle` is used.

``configLabel``, ``valueLabel``, ``tokenLabel``, ``defaultLabel``
   These are the labels of the AES key objects in the slot.

.. note:: If you are running a LunaSA HA group you must use the labels. The handles will not work.
   
``password``
   Here you can enter the password of the partition.
   If the password is not specified, you can pass it to LinOTP later.
   
.. note:: Instead of using the name "lunasa" you can use any other specifier.
   
Partition Password
~~~~~~~~~~~~~~~~~~

If you do not want to store the password in the `linotp.ini` you can 
pass this to LinOTP manually.

After starting the LinOTP service you can check the security module like this::

   linotpadm.py -U https://localhost -a admin -C securitymodule
   
You will get the following response::

   {   u'status': True,
    u'value': {   u'setupSecurityModule': {   u'activeSecurityModule': u'lunasa',
                                              u'connected': True}}}
                                              
If ``connected`` is ``False`` then you need to provide the partition password for the HSM slot::

    linotpadm.py -U https://localhost -a admin -C securitymodule --module=lunasa
    
Now you will be asked for the password of the partition.