-
Notifications
You must be signed in to change notification settings - Fork 4
/
README
143 lines (104 loc) · 5.45 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
README for the hash-sigs package: an implementation of the
Leighton-Micali Hierarchical Signature System (HSS).
Introduction
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.
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 file
Requirements
- a Python interpreter version 2.7.3 or greater
- the pycrypto package (https://pypi.python.org/pypi/pycrypto)
Usage
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.
Testing
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
13ba92228a856eb715861f5cfb9782bc
16d2512cdeb85bf080a9fae16b56cbfc
710bf44b69fef6bec99a35eaec062c27
K be9d1745e370334297aaf05fcefa2c84
9fe41c59b3321f883f54c9620a11d959
--------------------------------------------
--------------------------------------------
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
above.