2.10. Security Modules¶
Note
For a normal installation this section can be safely ignored.
privacyIDEA provides a security module that takes care of
- encrypting the token seeds,
- encrypting passwords from the configuration like the LDAP password,
- creating random numbers,
- and hashing values.
Note
The Security Module concept can also be used to add a Hardware Security Module to perform the above mentioned tasks.
2.10.1. Default Security Module¶
The default security module is implemented with the operating systems
capabilities. The encryption key is located in a file enckey specified via
PI_ENCFILE in the configuration file (The Config File).
This enckey contains three 32byte keys and is thus 96 bytes. This file has to be protected. So the access rights to this file are set accordingly.
In addition you can encrypt this encryption key with an additional password. In this case, you need to enter the password each time the privacyIDEA server is restarted and the password for decrypting the enckey is kept in memory.
The pi-manage Script contains the instruction how to encrypt the enckey
After starting the server, you can check, if the encryption key is accessible. To do so run:
privacyidea -U <yourserver> --admin=<youradmin> securitymodule
The output will contain "is_ready": True to signal that the encryption
key is operational.
If it is not yet operational, you need to pass the password to the privacyIDEA server to decrypt the encryption key. To do so run:
privacyidea -U <yourserver> --admin=<youradmin> securitymodule \
--module=default
Note
If the security module is not operational yet, you might get an error message “HSM not ready.”.
2.10.2. PKCS11 Security Module¶
The PKCS11 Security Module can be used to encrypt data with an hardware security module, that is connected via the PKCS11 interface. To encrypt and decrypt data you can use an RSA key pair that is stored on the HSM.
To activate this module add the following to the configuration file (The Config File)
PI_HSM_MODULE = “privacyidea.lib.security.pkcs11.PKCS11SecurityModule”
Additional attributes are
PI_HSM_MODULE_MODULE which takes the pkcs11 library. This is the full
specified path to the shared object file in the file system.
PI_HSM_MODULE_KEY_ID is the key id (integer) on the HSM.
2.10.3. AES HSM Security Module¶
The AES Hardware Security Module can be used to encrypt data with an hardware security module (HSM) connected via the PKCS11 interface. This module allows to use AES keys stored in the HSM to encrypt and decrypt data.
This module uses three keys, similarly to the content of
PI_ENCFILE, identified as token, config and value.
To activate this module add the following to the configuration file (The Config File)
PI_HSM_MODULE = “privacyidea.lib.security.aeshsm.AESHardwareSecurityModule”
Additional attributes are
PI_HSM_MODULE_MODULE which takes the pkcs11 library. This is the full
specified path to the shared object file in the file system.
PI_HSM_MODULE_SLOT is the slot on the HSM where the keys are
located (default: 1).
PI_HSM_MODULE_PASSWORD is the password to access the slot.
PI_HSM_MODULE_KEY_LABEL is the label prefix for the keys on the
HSM (default: privacyidea). In order to locate the keys, the
module will search for key with a label equal to the concatenation of
this prefix, _ and the key identifier (respectively token,
config and value).
PI_HSM_MODULE_KEY_LABEL_TOKEN is the label for token key
(defaults to value based on PI_HSM_MODULE_KEY_LABEL setting).
PI_HSM_MODULE_KEY_LABEL_CONFIG is the label for config key
(defaults to value based on PI_HSM_MODULE_KEY_LABEL setting).
PI_HSM_MODULE_KEY_LABEL_VALUE is the label for value key
(defaults to value based on PI_HSM_MODULE_KEY_LABEL setting).
