hsslms package

Submodules

hsslms.hss module

Hierarchical Signatures

For reference see RFC 8554, section 6.

class hsslms.hss.HSS_Priv(lmstypecodes, otstypecode, num_cores=None)[source]

Bases: object

A class used to hold the private key of Hierarchical Signatures (HSS)

For a reference see RFC 8554, section 6.

This class can be used to generate the belonging public key HSS_Pub.

Parameters:

lmstypecodes (list of LMS_ALGORITHM_TYPE) – List of enumeration of Leighton-Micali Signatures (LMS) algorithm types
otstypecode (LMOTS_ALGORITHM_TYPE) – Enumeration of Leighton-Micali One-Time-Signatures (LMOTS) algorithm types
num_cores (int, None, optional) – the number of CPU cores used for key generation, None=all cores

gen_pub()[source]

Computes the public key associated with the private key in this class.

Returns:: The public key belonging to this private key.
Return type:: HSS_Pub

get_avail_signatures()[source]

Computes the numbers of availalbe signatures.

Every invokation of the ‘sign’-Method reduces this number by one.

Returns:: The remaining number of signatures that can be generated.
Return type:: int

info()[source]

sign(message)[source]

Signature Generation of HSS

Signs a message with the private key associated with the class.

Parameters:: message (bytes, BufferedReader) – Message to be signed
Raises:: FAILURE – If a signature has already been computed, or for other technical reason
Returns:: The signature to message.
Return type:: bytes

class hsslms.hss.HSS_Pub(pubkey)[source]

Bases: object

A class used to hold the public key of Hierarchical Signatures (HSS)

This hierarchical scheme uses LMS as a component.

For a reference see RFC 8554, section 6.

Parameters:: pubkey (bytes) – u32str(L) || LMS Public Key[0]
Raises:: INVALID – If the public is invalid.

get_pubkey()[source]

info()[source]

verify(message, signature)[source]

Signature Verification of HSS

Tries to verify the signature of a message with the public key associated with the class.

Parameters:

message (bytes, BufferedReader) – Message to be verified with signature
signature (bytes) – Signature belonging to the message

Raises:

INVALID – If signature is invalid.

hsslms.lmots module

LM-OTS One-Time Signatures

For reference see RFC 8554, section 4.

class hsslms.lmots.LM_OTS_Priv(typecode, I, q, SEED)[source]

Bases: object

A class used to hold the private key of LM-OTS One-Time Signatures (LMOTS)

For a reference see RFC 8554, section 4.

This class can be used to generate the belonging public key LM_OTS_Pub.

Parameters:

typecode (LMOTS_ALGORITHM_TYPE) – Enumeration of Leighton-Micali One-Time-Signatures (LMOTS) algorithm types
I (bytes) – 16 random bytes
q (int) – 32-bit number / no.
SEED (bytes) – 32 random bytes for PRNG for LM_OTS

gen_pub()[source]

Computes the public key associated with the private key in this class.

Returns:: The public key belonging to this private key.
Return type:: LM_OTS_Pub

gen_pub_K()[source]

sign(message)[source]

Signature Generation of LMOTS

Signs a message with the private key associated with the class.

Parameters:: message (bytes, BufferedReader) – Message to be signed
Raises:: FAILURE – If a signature has already been computed, or for other technical reason
Returns:: The signature to message.
Return type:: bytes

class hsslms.lmots.LM_OTS_Pub(pubkey)[source]

Bases: object

A class used to hold the public key of LM-OTS One-Time Signatures (LMOTS)

For a reference see RFC 8554, section 4.

Parameters:: pubkey (bytes) – typecode || I || q || K

verify(message, signature)[source]

Signature Verification of LMOTS

Tries to verify the signature of a message with the public key associated with the class.

Parameters:

message (bytes, BufferedReader) – Message to be verified with signature
signature (bytes) – Signature belonging to the message

Raises:

INVALID – If signature is invalid.

hsslms.lms module

Leighton-Micali Signatures

For reference see RFC 8554, section 5.

class hsslms.lms.LMS_Priv(typecode, otstypecode, num_cores=None)[source]

Bases: object

A class used to hold the private key of Leighton-Micali Signatures (LMS)

For a reference see RFC 8554, section 5.

This class can be used to generate the belonging public key LMS_Pub.

Parameters:

typecode (LMS_ALGORITHM_TYPE) – Enumeration of Leighton-Micali Signatures (LMS) algorithm types
otstypecode (LMOTS_ALGORITHM_TYPE) – Enumeration of Leighton-Micali One-Time-Signatures (LMOTS) algorithm types
num_cores (int, None, optional) – the number of CPU cores used for key generation, None=all cores

gen_pub()[source]

Computes the public key associated with the private key in this class.

Returns:: The public key belonging to this private key.
Return type:: LMS_Pub

get_avail_signatures()[source]

Computes the numbers of availalbe signatures.

Every invokation of the ‘sign’-Method reduces this number by one.

Returns:: The remaining number of signatures that can be generated.
Return type:: int

sign(message)[source]

Signature Generation of LMS

Signs a message with the private key associated with the class.

Parameters:: message (bytes, BufferedReader) – Message to be signed
Raises:: FAILURE – If a signature has already been computed, or for other technical reason
Returns:: The signature to message.
Return type:: bytes

class hsslms.lms.LMS_Pub(pubkey)[source]

Bases: object

A class used to hold the public key of Leighton-Micali Signatures (LMS)

For a reference see RFC 8554, section 5.

Parameters:: pubkey (bytes) – u32str(type) || u32str(otstype) || I || T[1]
Raises:: INVALID – If the public is invalid.

get_pubkey()[source]

info()[source]

verify(message, signature)[source]

Signature Verification of LMS

Tries to verify the signature of a message with the public key associated with the class.

Parameters:

message (bytes, BufferedReader) – Message to be verified with signature
signature (bytes) – Signature belonging to the message

Raises:

INVALID – If signature is invalid.

hsslms.pershss module

Created on Sat Jan 1 20:00:55 2022

@author: mvr

class hsslms.pershss.PersHSS_Priv(lmstypecodes, otstypecode, filename, password, frequence, num_cores)[source]

Bases: HSS_Priv

A class derived from HSS_Priv.

It is used to generate the private key and derive the public key of a Hierarchical Signature System (HSS) The private key is signed and stored in an encrypted file.

Parameters:

lmstypecodes – List of LMS_ALGORITHM_TYPE
otstypecode – LMOTS_ALGORITHM_TYPE
filename (str) – holds the name of the file to store the key
password (bytes) – password to sign and encrypt the file
frequence (int) – frequnce at which the key is stored to a file

FILEHEADER = b'PersHSS_Priv_v\x000.1.3'

from_file(password)[source]

A key, HSS_Priv, is loaded from a password-protected file.

Frequnce signatures are skipped to ensure that no private key is used more than once.

Parameters:

filename (str) – name of the file
password (bytes) – password of the file

Raises:

FAILURE – if the key cannot be loaded

Returns:

HSS_Priv

save()[source]: The key is saved.

sign(message)[source]

Signs the message with the private key associated with the class.

The key is automatically stored to disk after frequnce signatures.

Parameters:: message (bytes, BufferedReader) – Message to be signed
Raises:: FAILURE – If a signature has already been computed, or for other technical reason
Returns:: The signature to message.
Return type:: bytes

hsslms.pershss.kdf(salt, password)[source]

hsslms.restricted_unpickler module

This module is for safe unpickling a HSS Private Key.

class hsslms.restricted_unpickler.RestrictedUnpickler(file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=())[source]

Bases: Unpickler

Safe unpickle a HSS Private Key

find_class(module, name)[source]

Return an object from a specified module.

If necessary, the module will be imported. Subclasses may override this method (e.g. to restrict unpickling of arbitrary classes and functions).

This method is called whenever a class or a function object is needed. Both arguments passed are str objects.

hsslms.restricted_unpickler.restricted_loads(s)[source]: Helper function analogous to pickle.loads().

hsslms.utils module

Created on Sat Jan 1 11:48:07 2022

@author: mvr

exception hsslms.utils.FAILURE[source]

Bases: Exception

Exception for general technical failures , e.g. if no private key is left to sign.

exception hsslms.utils.INVALID[source]

Bases: Exception

Exception for an invalid signature.

class hsslms.utils.LMOTS_ALGORITHM_TYPE(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enumeration of Leighton-Micali One-Time-Signatures (LMOTS) algorithm types, see rfc8554.

H: Hashfunction

n

Outputlength of the hashfunction

Type:: int

w

number of simultanious signes bits

Type:: int

p

internal dependent parameter

Type:: int

ls

internal dependent parameter

Type:: int

property H

LMOTS_SHA256_N24_W1 = 5

LMOTS_SHA256_N24_W2 = 6

LMOTS_SHA256_N24_W4 = 7

LMOTS_SHA256_N24_W8 = 8

LMOTS_SHA256_N32_W1 = 1

LMOTS_SHA256_N32_W2 = 2

LMOTS_SHA256_N32_W4 = 3

LMOTS_SHA256_N32_W8 = 4

property ls

property n

property p

property w

class hsslms.utils.LMS_ALGORITHM_TYPE(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enumeration of Leighton-Micali Signatures (LMS) algorithm types, see rfc8554.

H: Hashfunction

m

Outputlength of the hashfunction

Type:: int

h

height of the tree

Type:: int

property H

LMS_SHA256_M24_H10 = 11

LMS_SHA256_M24_H15 = 12

LMS_SHA256_M24_H20 = 13

LMS_SHA256_M24_H25 = 14

LMS_SHA256_M24_H5 = 10

LMS_SHA256_M32_H10 = 6

LMS_SHA256_M32_H15 = 7

LMS_SHA256_M32_H20 = 8

LMS_SHA256_M32_H25 = 9

LMS_SHA256_M32_H5 = 5

property h

property m

hsslms.utils.cksm(S, w, n, ls)[source]

hsslms.utils.coef(S, i, w)[source]

hsslms.utils.strTou32(S)[source]

hsslms.utils.u16str(i)[source]

hsslms.utils.u32str(i)[source]

hsslms.utils.u8str(i)[source]

hsslms.lmswrapper module

class hsslms.lmswrapper.LMS_Wrapper_Priv(lmstypecodes, otstypecode, filename, password, frequence=None, num_cores=None)[source]

Bases: LMS_Priv

Class derived from LMS_Priv.

It is used to generate the private key and derive the public key of a LMS signature system. The private key is signed and stored in an encrypted file.

Parameters:

lmstypecodes – List of LMS_ALGORITHM_TYPE
otstypecode – LMOTS_ALGORITHM_TYPE
filename (str) – holds the name of the file to store the key
password (bytes) – password to sign and encrypt the file
frequence (int) – frequnce at which the key is stored to a file

FILEHEADER = b'LMSWrapper_Priv_v\x000.1'

from_file(filename, password)[source]

A key, LMS_Priv is loaded from a password-protected file.

Frequence signatures are skipped to ensure that no private key is used more than once.

Raises:: FAILURE – if the key cannot be loaded
Returns:: LMS_Priv

save()[source]: This method is to save the key.

sign(message)[source]

Signs the message with the private key associated with the class.

The key is automatically stored to disk after frequence signatures.

Parameters:: message (bytes, BufferedReader) – Message to be signed
Raises:: FAILURE – If a signature has already been computed, or for other technical reason
Returns:: The signature to message.
Return type:: bytes

verify(message, signature, public_key)[source]

Signature is verified using public key.

Parameters:

message –
signature –
public_key –

Returns:

True if signature is correct else False

hsslms.lmswrapper.kdf(salt, password)[source]

Module contents

Leighton-Micali Hash-Based Signatures

This modulue provides an implementation of Leighton-Micali Hash-Based Signatures in Python according to RFC 8554, https://www.rfc-editor.org/rfc/rfc8554.html.

For LM-OTS One-Time Signatures the classes LM_OTS_Priv and LM_OTS_Pub can be used.

For Leighton-Micali Signatures the classes LMS_Priv and LMS_Pub can be used.

For Hierarchical Signatures the classes HSS_Priv and HSS_Pub can be used.

There is also a command line script available hsslms which can be used for Hierarchical Signatures.

Example

LM-OTS One-Time Signatures::

from os import urandom from hsslms import LM_OTS_Priv

# generate a one-time private key sk = LM_OTS_Priv(LMOTS_ALGORITHM_TYPE.LMOTS_SHA256_N32_W2, urandom(16), 0) # sign a message with the private key signature = sk.sign(b’abc’) # compute the related public key vk = sk.gen_pub() # verify the signature, if invalid an exception will be raised vk.verify(b’abc’, signature)

Leighton-Micali Signatures::

from os import urandom from hsslms import LMS_Priv

# generate a private key sk = LMS_Priv(LMS_ALGORITHM_TYPE.LMS_SHA256_M32_H10, LMOTS_ALGORITHM_TYPE.LMOTS_SHA256_N32_W8) # sign a message with the private key, in total 2^10 signatures are available signature = sk.sign(b’abc’) # compute the related public key vk = sk.gen_pub() # verify the signature, if invalid an exception will be raised vk.verify(b’abc’, signature)

Hierarchical Signatures::

from os import urandom from hsslms import HSS_Priv

# generate a private key sk = HSS_Priv([LMS_ALGORITHM_TYPE.LMS_SHA256_M32_H10]*2, LMOTS_ALGORITHM_TYPE.LMOTS_SHA256_N32_W1) # sign a message with the private key, in total 2^20 signatures are available signature = sk.sign(b’abc’) # compute the related public key vk = sk.gen_pub() # verify the signature, if invalid an exception will be raised vk.verify(b’abc’, signature)

exception hsslms.FAILURE[source]

Bases: Exception

Exception for general technical failures , e.g. if no private key is left to sign.

class hsslms.HSS_Priv(lmstypecodes, otstypecode, num_cores=None)[source]

Bases: object

A class used to hold the private key of Hierarchical Signatures (HSS)

For a reference see RFC 8554, section 6.

This class can be used to generate the belonging public key HSS_Pub.

Parameters:

lmstypecodes (list of LMS_ALGORITHM_TYPE) – List of enumeration of Leighton-Micali Signatures (LMS) algorithm types
otstypecode (LMOTS_ALGORITHM_TYPE) – Enumeration of Leighton-Micali One-Time-Signatures (LMOTS) algorithm types
num_cores (int, None, optional) – the number of CPU cores used for key generation, None=all cores

gen_pub()[source]

Computes the public key associated with the private key in this class.

Returns:: The public key belonging to this private key.
Return type:: HSS_Pub

get_avail_signatures()[source]

Computes the numbers of availalbe signatures.

Every invokation of the ‘sign’-Method reduces this number by one.

Returns:: The remaining number of signatures that can be generated.
Return type:: int

info()[source]

sign(message)[source]

Signature Generation of HSS

Signs a message with the private key associated with the class.

Parameters:: message (bytes, BufferedReader) – Message to be signed
Raises:: FAILURE – If a signature has already been computed, or for other technical reason
Returns:: The signature to message.
Return type:: bytes

class hsslms.HSS_Pub(pubkey)[source]

Bases: object

A class used to hold the public key of Hierarchical Signatures (HSS)

This hierarchical scheme uses LMS as a component.

For a reference see RFC 8554, section 6.

Parameters:: pubkey (bytes) – u32str(L) || LMS Public Key[0]
Raises:: INVALID – If the public is invalid.

get_pubkey()[source]

info()[source]

verify(message, signature)[source]

Signature Verification of HSS

Tries to verify the signature of a message with the public key associated with the class.

Parameters:

message (bytes, BufferedReader) – Message to be verified with signature
signature (bytes) – Signature belonging to the message

Raises:

INVALID – If signature is invalid.

exception hsslms.INVALID[source]

Bases: Exception

Exception for an invalid signature.

class hsslms.LMOTS_ALGORITHM_TYPE(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enumeration of Leighton-Micali One-Time-Signatures (LMOTS) algorithm types, see rfc8554.

H: Hashfunction

n

Outputlength of the hashfunction

Type:: int

w

number of simultanious signes bits

Type:: int

p

internal dependent parameter

Type:: int

ls

internal dependent parameter

Type:: int

property H

LMOTS_SHA256_N24_W1 = 5

LMOTS_SHA256_N24_W2 = 6

LMOTS_SHA256_N24_W4 = 7

LMOTS_SHA256_N24_W8 = 8

LMOTS_SHA256_N32_W1 = 1

LMOTS_SHA256_N32_W2 = 2

LMOTS_SHA256_N32_W4 = 3

LMOTS_SHA256_N32_W8 = 4

property ls

property n

property p

property w

class hsslms.LMS_ALGORITHM_TYPE(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enumeration of Leighton-Micali Signatures (LMS) algorithm types, see rfc8554.

H: Hashfunction

m

Outputlength of the hashfunction

Type:: int

h

height of the tree

Type:: int

property H

LMS_SHA256_M24_H10 = 11

LMS_SHA256_M24_H15 = 12

LMS_SHA256_M24_H20 = 13

LMS_SHA256_M24_H25 = 14

LMS_SHA256_M24_H5 = 10

LMS_SHA256_M32_H10 = 6

LMS_SHA256_M32_H15 = 7

LMS_SHA256_M32_H20 = 8

LMS_SHA256_M32_H25 = 9

LMS_SHA256_M32_H5 = 5

property h

property m

class hsslms.LMS_Priv(typecode, otstypecode, num_cores=None)[source]

Bases: object

A class used to hold the private key of Leighton-Micali Signatures (LMS)

For a reference see RFC 8554, section 5.

This class can be used to generate the belonging public key LMS_Pub.

Parameters:

typecode (LMS_ALGORITHM_TYPE) – Enumeration of Leighton-Micali Signatures (LMS) algorithm types
otstypecode (LMOTS_ALGORITHM_TYPE) – Enumeration of Leighton-Micali One-Time-Signatures (LMOTS) algorithm types
num_cores (int, None, optional) – the number of CPU cores used for key generation, None=all cores

gen_pub()[source]

Computes the public key associated with the private key in this class.

Returns:: The public key belonging to this private key.
Return type:: LMS_Pub

get_avail_signatures()[source]

Computes the numbers of availalbe signatures.

Every invokation of the ‘sign’-Method reduces this number by one.

Returns:: The remaining number of signatures that can be generated.
Return type:: int

sign(message)[source]

Signature Generation of LMS

Signs a message with the private key associated with the class.

Parameters:: message (bytes, BufferedReader) – Message to be signed
Raises:: FAILURE – If a signature has already been computed, or for other technical reason
Returns:: The signature to message.
Return type:: bytes

class hsslms.LMS_Pub(pubkey)[source]

Bases: object

A class used to hold the public key of Leighton-Micali Signatures (LMS)

For a reference see RFC 8554, section 5.

Parameters:: pubkey (bytes) – u32str(type) || u32str(otstype) || I || T[1]
Raises:: INVALID – If the public is invalid.

get_pubkey()[source]

info()[source]

verify(message, signature)[source]

Signature Verification of LMS

Tries to verify the signature of a message with the public key associated with the class.

Parameters:

message (bytes, BufferedReader) – Message to be verified with signature
signature (bytes) – Signature belonging to the message

Raises:

INVALID – If signature is invalid.

class hsslms.LM_OTS_Priv(typecode, I, q, SEED)[source]

Bases: object

A class used to hold the private key of LM-OTS One-Time Signatures (LMOTS)

For a reference see RFC 8554, section 4.

This class can be used to generate the belonging public key LM_OTS_Pub.

Parameters:

typecode (LMOTS_ALGORITHM_TYPE) – Enumeration of Leighton-Micali One-Time-Signatures (LMOTS) algorithm types
I (bytes) – 16 random bytes
q (int) – 32-bit number / no.
SEED (bytes) – 32 random bytes for PRNG for LM_OTS

gen_pub()[source]

Computes the public key associated with the private key in this class.

Returns:: The public key belonging to this private key.
Return type:: LM_OTS_Pub

gen_pub_K()[source]

sign(message)[source]

Signature Generation of LMOTS

Signs a message with the private key associated with the class.

Parameters:: message (bytes, BufferedReader) – Message to be signed
Raises:: FAILURE – If a signature has already been computed, or for other technical reason
Returns:: The signature to message.
Return type:: bytes

class hsslms.LM_OTS_Pub(pubkey)[source]

Bases: object

A class used to hold the public key of LM-OTS One-Time Signatures (LMOTS)

For a reference see RFC 8554, section 4.

Parameters:: pubkey (bytes) – typecode || I || q || K

verify(message, signature)[source]

Signature Verification of LMOTS

Tries to verify the signature of a message with the public key associated with the class.

Parameters:

message (bytes, BufferedReader) – Message to be verified with signature
signature (bytes) – Signature belonging to the message

Raises:

INVALID – If signature is invalid.

class hsslms.PersHSS_Priv(lmstypecodes, otstypecode, filename, password, frequence, num_cores)[source]

Bases: HSS_Priv

A class derived from HSS_Priv.

It is used to generate the private key and derive the public key of a Hierarchical Signature System (HSS) The private key is signed and stored in an encrypted file.

Parameters:

lmstypecodes – List of LMS_ALGORITHM_TYPE
otstypecode – LMOTS_ALGORITHM_TYPE
filename (str) – holds the name of the file to store the key
password (bytes) – password to sign and encrypt the file
frequence (int) – frequnce at which the key is stored to a file

FILEHEADER = b'PersHSS_Priv_v\x000.1.3'

from_file(password)[source]

A key, HSS_Priv, is loaded from a password-protected file.

Frequnce signatures are skipped to ensure that no private key is used more than once.

Parameters:

filename (str) – name of the file
password (bytes) – password of the file

Raises:

FAILURE – if the key cannot be loaded

Returns:

HSS_Priv

save()[source]: The key is saved.

sign(message)[source]

Signs the message with the private key associated with the class.

The key is automatically stored to disk after frequnce signatures.

Parameters:: message (bytes, BufferedReader) – Message to be signed
Raises:: FAILURE – If a signature has already been computed, or for other technical reason
Returns:: The signature to message.
Return type:: bytes