README for the hash-sigs package: an implementation of theLeighton-Micali Hierarchical Signature System (HSS).IntroductionThis package contains an experimental implementation of the hash-baseddigital signatures algorithm specified in the Internet Draftdraft-mcgrew-hash-sigs-05.txt, intended for the purposes ofunderstanding that specification and gaining practical experienceworking with hash based signatures.  It is NOT intended for use insecurity critical applications.  The implementation aims forreadability over other criteria such as performance or fullyexploiting the Python language.Please see the security considerations section of the draft, and notethat private key files MUST NOT be copied and MUST NOT be cloned aspart of a Virtual Machine snapshot (either a full snapshot or a volumesnapshot), or else security may be lost.  The application checks tosee if private key files have been accidentially copied, but thesechecks cannot detect VM cloning.Contents   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 fileRequirements   - a Python interpreter version 2.7.3 or greater   - the pycrypto package (https://pypi.python.org/pypi/pycrypto)UsageThe hss.py program can generate public/private keypairs, sign files,and verify signatures on files, as well as perform automated testingand read and pretty-print keys and signatures.  It uses detachedsignatures, that is, the signature of a file with the path <name> iswritten to a separate file with the path <name>.sig.  Public andprivate keys are stored in files named <keyname>.pub and<keyname>.prv, respectively, where <keyname> is a string provided tothe key generation process.  The suffixes .sig, .pub, and .prv MUST bepresent in order for hss.py to correctly process the files.  Thisconvention ensures that the file formats exactly match the draftspecification, 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>.pubhss.py sign <file> [ <file2> ... ] <prvname>   updates <prvname>, then writes signature of <file> to <file>.sighss.py verify <pubname> <file> [ <file2> ... ]   verifies file using public keyhss.py read <file> [ <file2> ... ]   read and pretty-print .sig, .pub, .prv file(s)hss.py test [all | hss | lms | lmots | checksum ]   performs algorithm testsAs hss.py is an executable file, it has the path to its pythoninterpreter hardcoded as /usr/bin/python.  To run the program when thepython interpreter is in another location on the filesystem, use thecommand 'python hss.py' instead of 'hss.py', followed by the argumentsas above, or edit the path as needed.  TestingThe hss.py test command performs several automated tests, includingconsistency checking (signing then verifying) with valid signatures,sanity checks on invalid signatures, checks that verify that privatekeys cannot be overused, and fuzz-testing style checks that manglesignatures and private keys.  These checks are performed on all of thesignature components in the HSS draft: LMOTS, LMS, and HSS.To test the command-line functionality of hss.py, the bash scripthss-test.sh in the test/ subdirectory generates a keypair, signs a setof files, verifies the signatures, and then generates a set of 'dump'files containing the pretty-printed format.  Public key and signature formatsWith the read command, hss.py will print out a signature or public keyfile in a human-readable format.  This can be useful as a way tounderstand how the different data elements are serialized into bytestrings.  An example of the output of the read command is: --------------------------------------------HSS public keylevels-1    00000001--------------------------------------------LMS public keyLMS type    00000001                         # LMS_SHA256_M32_H5LMOTS_type  00000004                         # LMOTS_SHA256_N32_W8I           968ae04d83fc24cb75a96a474dab0590            13ba92228a856eb715861f5cfb9782bc            16d2512cdeb85bf080a9fae16b56cbfc            710bf44b69fef6bec99a35eaec062c27K           be9d1745e370334297aaf05fcefa2c84            9fe41c59b3321f883f54c9620a11d959----------------------------------------------------------------------------------------The middle column contains a hexadecimal string that corresponds tothe byte string of the object, when read from left to right and top tobottom.  That is, if hexdump -C is run on the same file, it wouldreveal that the object is the hex string    000000010000000100000004968ae04d83fc24cb75a96a474dab0590 ...The left-hand column contains the names of the variables thatcorrespond to the byte strings in the middle column.  The rightmostcolumn 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 howthe LMS public key is contained in the HSS public key in the exampleabove.