6.1.1.3.1.4.1.2. linotp.lib.security.pkcs11 module

This Security module (hsm) is used to access hardware security modules via PKCS11 for encrypting and decrypting the data

linotp.ini: linotpActiveSecurityModule = lunasa linotpSecurity.lunasa.module = linotp.lib.security.pkcs11.Pkcs11SecurityModule linotpSecurity.lunasa.library = libCryptoki2_64.so linotpSecurity.lunasa.pinHandle =21 linotpSecurity.lunasa.valueHandle =22 linotpSecurity.lunasa.passwordHandle =23 linotpSecurity.lunasa.defaultHandle =22 linotpSecurity.lunasa.configLabel = config linotpSecurity.lunasa.tokenLabel = token linotpSecurity.lunasa.valueLabel = value linotpSecurity.lunasa.password = 6SNq-L9WL-SSW4-NGNL linotpSecurity.lunasa.slotid = 1 linotpActiveSecurityModule = lunasa

class linotp.lib.security.pkcs11.CK_ATTRIBUTE

Bases: _ctypes.Structure

pValue

Structure/Union member

type

Structure/Union member

ulValueLen

Structure/Union member

class linotp.lib.security.pkcs11.CK_MECHANISM

Bases: _ctypes.Structure

mechanism

Structure/Union member

pParameter

Structure/Union member

usParameterLen

Structure/Union member

class linotp.lib.security.pkcs11.CK_TOKEN_INFO

Bases: _ctypes.Structure

firmwareVersion

Structure/Union member

flags

Structure/Union member

hardwareVersion

Structure/Union member

label

Structure/Union member

manufacturerID

Structure/Union member

model

Structure/Union member

serialNumber

Structure/Union member

ulFreePrivateMemory

Structure/Union member

ulFreePublicMemory

Structure/Union member

ulMaxPinLen

Structure/Union member

ulMaxRwSessionCount

Structure/Union member

ulMaxSessionCount

Structure/Union member

ulMinPinLen

Structure/Union member

ulRwSessionCount

Structure/Union member

ulSessionCount

Structure/Union member

ulTotalPrivateMemory

Structure/Union member

ulTotalPublicMemory

Structure/Union member

utcTime

Structure/Union member

class linotp.lib.security.pkcs11.CK_VERSION

Bases: _ctypes.Structure

major

Structure/Union member

minor

Structure/Union member

class linotp.lib.security.pkcs11.Pkcs11SecurityModule(config=None)

Bases: linotp.lib.security.SecurityModule

Class that handles all AES stuff

createAES(ks=32, label='new AES Key')

Creates a new AES key with the given label and the given length

returns the handle

decrypt(data, iv, id=0)

decrypts the given data, using the IV and the key specified by the handle

possible id’s are:

0 1 2

decryptPassword(cryptPass)

dedicated security module methods: decryptPassword which used one slot id to decryt a string

@param cryptPassword: the crypted password - leading iv, seperated by the ‘:’ @param cryptPassword: byte string

@return: decrypted data @rtype: byte string

decryptPin(cryptPin)

dedicated security module methods: decryptPin which used one slot id to decryt a string

@param cryptPin: the crypted pin - - leading iv, seperated by the ‘:’ @param cryptPin: byte string

@return: decrypted data @rtype: byte string

decrypt_soft(data, iv, key)

Decrypt in CPU

encrypt(data, iv, id=0)

encrypts the given input data

AES hat eine blocksize von 16 byte. Daher muss die data ein vielfaches von 16 sein und der IV im Falle von CBC auch 16 byte lang.

encryptPassword(password)

dedicated security module methods: encryptPassword which used one slot id to encrypt a string

@param password: the to be encrypted password @param password: byte string

@return: encrypted data - leading iv, seperated by the ‘:’ @rtype: byte string

encryptPin(pin)

dedicated security module methods: encryptPin which used one slot id to encrypt a string

@param pin: the to be encrypted pin @param pin: byte string

@return: encrypted data - leading iv, seperated by the ‘:’ @rtype: byte string

find_aes_keys(label='testAES', wanted=1)

Find and AES key with the given label The number of keys to be found is restricted by “wanted”

Returns

• the number of keys and
• the handle to the key

gettokeninfo(slotid=0)

This returns a dictionary with the token info

initpkcs11()

Initialize the PKCS11 library

isReady()

login(password=None, slotid=0)

Open a session on the first token

After this, we got a self.hSession

logout()

closes the existing session

pad(unpadded_str, block=16)

PKCS7 padding pads the missing bytes with the value of the number of the bytes. If 4 bytes are missing, this missing bytes are filled with 

Parameters:

• unpadded_str (str) – The string to pad
• block (int) – Block size

Returns:

padded string

Return type:

str

populate_handles()

In a HA Group of LunaSAs the handle do not exist. They first need to be populated

The Label overwrites the handles!

random(l=32)

create a random value and return it l specifies the length of the random data to be created.

setup_module(params)

used to set the password, if the password is not contained in the config file

unpad(padded_str, block=16)

This removes and checks the PKCS #7 padding.

Parameters:

• padded_str (str) – The string to unpad
• block (int) – Block size

Raises ValueError:  

If padded_str is not correctly padded a ValueError can be raised. This depends on the ‘pkcs11.accept_invalid_padding’ LinOTP config option. If set to False (default) ValueError is raised. The reason why the data is sometimes incorrectly padded is because the pad() method delivered with LinOTP version < 2.7.1 didn’t pad correctly when the data-length was a multiple of the block-length. Beware that in some cases (statistically about 0.4% of data-chunks whose length is a multiple of the block length) the incorrect padding can not be detected and incomplete data is returned. One example for this last case is when the data ends with the byte 0x01. This is recognized as legitimate padding and is removed before returning the data, thus removing a legitimate byte from the data and making it unusable. If you didn’t upgrade from a LinOTP version before 2.7.1 (or don’t use a PKCS#11 HSM) you will not be affected by this in any way. ValueError will of course also be raised if you data became corrupt for some other reason (e.g. disk failure) and can not be unpadded. In this case you should NOT set ‘pkcs11.accept_invalid_padding’ to True because your data will be unusable anyway.

Returns:

unpadded string or sometimes padded string when ‘pkcs11.accept_invalid_padding’ is set to True. See above.

Return type:

str

linotp.lib.security.pkcs11.main()

This module can be called to create an AES key.

Parameters are:

-p / –password= The Passwort of the partition. Can be ommitted. Then you are asked -s / –slot= The Slot number (default 0) -n / –name= The name of the AES key. -f / –find= Find the AES key -h / –help -e / –encrypt= Encrypt this data (also need slot and handle) -l / –label= Specify the label of the object for encryption

linotp.lib.security.pkcs11.output(loglevel, text)

linotp.lib.security.pkcs11.pkcs11error(rv)