A python implementation of Leighton-Micali hierarchical hash based signatures
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


README for the hash-sigs package: an implementation of the
Leighton-Micali Hierarchical Signature System (HSS).


This package contains an experimental implementation of the hash-based
digital signatures algorithm specified in the Internet Draft
draft-mcgrew-hash-sigs-05.txt, intended for the purposes of
understanding that specification and gaining practical experience
working with hash based signatures.  It is NOT intended for use in
security critical applications.  The implementation aims for
readability over other criteria such as performance or fully
exploiting the Python language.

Please see the security considerations section of the draft, and note
that private key files MUST NOT be copied and MUST NOT be cloned as
part of a Virtual Machine snapshot (either a full snapshot or a volume
snapshot), or else security may be lost.  The application checks to
see if private key files have been accidentially copied, but these
checks cannot detect VM cloning.


   hss.py  - a Python 2.7.3 implementation of the HSS scheme
   test/   - a subdirectory with a test script and test files
   LICENSE - stuff for lawyers
   AUTHORS - contributors
   README  - this file


   - a Python interpreter version 2.7.3 or greater
   - the pycrypto package (https://pypi.python.org/pypi/pycrypto)


The hss.py program can generate public/private keypairs, sign files,
and verify signatures on files, as well as perform automated testing
and read and pretty-print keys and signatures.  It uses detached
signatures, that is, the signature of a file with the path <name> is
written to a separate file with the path <name>.sig.  Public and
private keys are stored in files named <keyname>.pub and
<keyname>.prv, respectively, where <keyname> is a string provided to
the key generation process.  The suffixes .sig, .pub, and .prv MUST be
present in order for hss.py to correctly process the files.  This
convention ensures that the file formats exactly match the draft
specification, for clarity's sake.

hss.py expects that its first argument will be one of these commands:

   - genkey, to generate one or more public private keypairs,
   - sign, to sign one or more files,
   - verify, to verify one or more files,
   - read, to read and pretty-print one or more files,
   - test, to perform automated algorithmic consistency checks.

The syntax of these commands is shown by the usage statement:

hss.py genkey <name>
   creates <name>.prv and <name>.pub

hss.py sign <file> [ <file2> ... ] <prvname>
   updates <prvname>, then writes signature of <file> to <file>.sig

hss.py verify <pubname> <file> [ <file2> ... ]
   verifies file using public key

hss.py read <file> [ <file2> ... ]
   read and pretty-print .sig, .pub, .prv file(s)

hss.py test [all | hss | lms | lmots | checksum ]
   performs algorithm tests

As hss.py is an executable file, it has the path to its python
interpreter hardcoded as /usr/bin/python.  To run the program when the
python interpreter is in another location on the filesystem, use the
command 'python hss.py' instead of 'hss.py', followed by the arguments
as above, or edit the path as needed.  


The hss.py test command performs several automated tests, including
consistency checking (signing then verifying) with valid signatures,
sanity checks on invalid signatures, checks that verify that private
keys cannot be overused, and fuzz-testing style checks that mangle
signatures and private keys.  These checks are performed on all of the
signature components in the HSS draft: LMOTS, LMS, and HSS.

To test the command-line functionality of hss.py, the bash script
hss-test.sh in the test/ subdirectory generates a keypair, signs a set
of files, verifies the signatures, and then generates a set of 'dump'
files containing the pretty-printed format.  

Public key and signature formats

With the read command, hss.py will print out a signature or public key
file in a human-readable format.  This can be useful as a way to
understand how the different data elements are serialized into byte
strings.  An example of the output of the read command is: 

HSS public key
levels-1    00000001
LMS public key
LMS type    00000001                         # LMS_SHA256_M32_H5
LMOTS_type  00000004                         # LMOTS_SHA256_N32_W8
I           968ae04d83fc24cb75a96a474dab0590
K           be9d1745e370334297aaf05fcefa2c84

The middle column contains a hexadecimal string that corresponds to
the byte string of the object, when read from left to right and top to
bottom.  That is, if hexdump -C is run on the same file, it would
reveal that the object is the hex string 

   000000010000000100000004968ae04d83fc24cb75a96a474dab0590 ...

The left-hand column contains the names of the variables that
correspond to the byte strings in the middle column.  The rightmost
column contains the symbolic identifier associated with the typecodes.

Each object starts with a descriptive name, e.g. "HSS public key",
"LMS public key", and each object is surrounded by dashed lines.
These lines illustrate how one object can contain another, such as how
the LMS public key is contained in the HSS public key in the example