.. _securitymodule:

===============
Security Module
===============

Starting with LinOTP 2.5 it is supported to store the encryption key in Hardware Security Modules. 
Encryption and decryption can be performed in such a hardware module. LinOTP implements a concept 
of a security module abstraction layer i.e. even the old encryption key stored at ``/etc/linotp2/encKey``
now is handled via a security module. New modules can be added easily.
To define a module you need to configure this in the linotp.ini file. If you do not add anything, the 
old encryption key functionality is used.::

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

You can define several modules. LinOTP at the moment comes with a PKCS11 security module. To define, which module should be used the key linotpActiveSecurityModule is used which takes the identifier of the module.
To define a new module, you use the key linotpSecurity.lunasa.module, where “lunasa” is the identifier or the name of the module and the key takes the Python module.

The following keys are configuration that depend on the chosen module. In this case the PKCS11 module.::

  #Config depending on module
  linotpSecurity.lunasa.library = libCryptoki2_64.so 
  linotpSecurity.lunasa.configHandle = 21 
  linotpSecurity.lunasa.valueHandle = 22 
  linotpSecurity.lunasa.tokenHandle = 23 
  linotpSecurity.lunasa.defaultHandle = 22 
  linotpSecurity.lunasa.slotid = 1 

PKCS11 module and SafeNet LunaSA
--------------------------------

``library`` 
	defines the PKCS11 so library in your filesystem.

``slotid`` 
	is the slot of the PKCS11 module to use.

The ``configHandle``, ``valueHandle`` and ``tokenHandle`` 
	are the handles within the slot of the corresponding AES keys to do the encryption and decryption of the OTP PIN, of configuration values, OTP keys and passwords.
	The defaultHandle is used, If one of the other Handles is not defined.

Password handling
-----------------
Usually the PKCS11 device needs a password to access the slot. 
This password can either be defined in the linotp.ini file or needs to be passed to the LinOTP
server after it has started.
To define it in ``linotp.ini`` do it like this::

  linotpSecurity.lunasa.password = YourPassword

To pass the password later to the LinOTP server you can use the ``linotpadm.py`` command line client::

  % linotpadm.py --admin=admin --url=https://localhost -C securitymodule --module=default
	python yubikey module not available.
	please get it from https://github.com/Yubico/python-yubico if you want to enroll yubikeys
	No module named yubico
	Please enter password for 'admin':
	Please enter password for security module 'default':
	{ u'status': True,
	u'value': { u'setupSecurityModule': { u'activeSecurityModule': u'default',
	u'connected': True}}}

To check the status of the security module you can do this::
	
  % linotpadm.py --admin=admin --url=https://localhost -C securitymodule
	python yubikey module not available.
	please get it from https://github.com/Yubico/python-yubico if you want to enroll yubikeys
	No module named yubico
	Please enter password for 'admin':
	{ u'status': True,
	u'value': { u'setupSecurityModule': { u'activeSecurityModule': u'default',
	u'connected': True}}}