]> pd.if.org Git - zpackage/blob - doc/zpm-sign.8
package signature work
[zpackage] / doc / zpm-sign.8
1 .TH zpm-sign 8 2019-03-09 "ZPM 0.7.0"
2 .SH NAME
3 zpm-sign \- manage package signatures
4 .SH SYNOPSIS
5 .B zpm sign
6 [
7 .B \-vsge
8 ]
9 [
10 .B \-Hhrd
11 ]
12 [
13 .BI -o " outfile"
14 ]
15 [
16 .BI -i " input"
17 ]
18 [
19 .BI -k " keyid"
20 ]
21 [
22 .BI -I " inputhexstring"
23 ]
24 [
25 .BI -p " passphrase"
26 ]
27 [
28 .BI -m " messagestring"
29 ]
30 .RI [ file ]
31 .SH DESCRIPTION
32 \fBzpm-sign\fR
33 manages signatures on zpm packages.  It can generate signing keys,
34 sign files, and verify signatures.  The ed25519 algorithms are
35 used exclusively, and all the signature code is taken from the
36 ref10 implementation.
37 .PP
38 Private keys are potentially encrypted with chacha20 before storing
39 them on disk.
40 .PP
41 Signatures are always detached signatures.
42 .SS Specifying a key
43 The \-k option is used to specify a key.  Keys are looked for
44 in the keyring file (or taken literally from the command line
45 if the \-h option is given).
46 The \-i option can be used to specify a
47 key file to look for a key in.  If the \-k option is given, or the ZPM_KEY
48 environment variable is set, a key which matches that string in the id portion
49 of the key is looked for, otherwise the first secret key found is used.  If the
50 \-i option is not given, a key will be searched for in a file given with the
51 ZPM_KEYFILE environment variable or in ~/.zpm/key  Alternatively, a hex encoded
52 private key can be specified directly with the \-I option.  If several of these
53 options apply, The \-I option takes precedence.  I.e. command line beats
54 environment variables beats defaults.
55 .PP
56 If the private key needs a passphrase, it can be specified via the \-p
57 option or the ZPM_KEYPASS environment variable, neither of which
58 is secure.  Otherwise, if /dev/tty can be opened, zpm-sign will
59 attempt to ask for a passphrase.
60 .PP
61 For signing or generating a public key, a private key is looked for, and if not
62 specified, the first one found in the keyring file is used.
63 .PP
64 For signature verification, no key needs to be specified as the public
65 key is contained in the signature.
66 .SS Signing Mode
67 To sign data, use \-s
68 .PP
69 Inputs to a regular signature are:
70 .TP  the secret key used to sign the message,
71 See above for methods to specify a secret key.
72 .TP
73 Signature timestamp
74 Defaults to the current time read from the system clock.
75 Can be specified with the \-T option.
76 .TP
77 Expiration timestamp
78 Defaults to never.  Can be specified with the \-E optino.
79 .TP
80 The message to be signed.
81 Is read from stdin, a command line argument, or the \-m option.
82 If both an argument and a \-m option are given the \-m option wins.
83 .PP
84 When a raw signature is created (with the \-r option), the 
85 .PP
86 The signature is output to stdout, or the output file given with the
87 \-o option.  A signature packet is output unless the \-b option is given,
88 in which case only the hex encoded signature is output.
89 .SS Key Generation Mode
90 A new private key is generated with \-g
91 .SS Verification Mode
92 A signature can be verified with \-v
93 .SH OPTIONS
94 .TP
95 .B -r
96 Output the raw signature or key data without wrapping it in a
97 packet structure.
98 .TP
99 .B \-g
100 Generate a private key
101 .TP
102 .B \-e
103 Extract a public key from a private key.
104 .TP
105 .B \-s
106 Sign a file or message.  In addition to the message to be signed,
107 signature metadata is signed.
108 .TP
109 .B \-v
110 Verify a signature on a file or message.
111 .TP
112 .B \-h
113 hexencode values
114 .TP
115 .B \-d
116 Increase the debug level.  May be given more than once.
117 .TP
118 .B \-r
119 Output the raw signature, rather than a full zpm certificate.
120 This also just signs the data given, without any signature
121 metadata.
122 .TP
123 .BI \-p " passphrase"
124 Specify a passphrase to decrypt or encrypt a private key.  If not given here,
125 the environment variable ZPM_SIGN_PP is used.  Neither of these options
126 are very secure, the command line in particular is generally readable
127 by other processes.
128 .TP
129 .BI \-m " message"
130 Specify a message to be signed or verified.  If not set with the -m option, the
131 message is taken from file named with the first non-option argument.
132 .TP
133 .BI \-k " path"
134 Take the private key for message signing from the path given.  This
135 defaults to ~/.zpm/key.  If ~/.zpm/key is not found and the euid
136 is root, /var/lib/zpm/key is tried.
137 .TP
138 .BI \-K " key"
139 Take the private key from the command line argument.  This is not
140 particularly secure and is primarily intended for testing.
141 .TP
142 .BI \-S " sigstring"
143 Use sigstring as the signature to verify.
144 .TP
145 .BI \-m " message"
146 Specify a message to be signed or verified.  If not set with the -m option, the
147 message is taken from file named with the first non-option argument.
148 .TP
149 .BI \-t " timestamp"
150 Specify a timestamp to be used for signing instead of the current time.
151 Must be specified as a decimal representation of the unix timestamp
152 to be used.
153 .SH PACKET AND FILE FORMAT
154 .PP
155 Signatures and keys are output as hexencoded packet bytestrings.  All are 256
156 bytes, (512 bytes as hex encoded).  Reserved bytes in packet formats must be
157 zero.  The last 8 bytes are reserved.
158 .PP
159 On disk format is a series of 32 bytes, hex encoded, followed by
160 a newline.  This takes one line per 32 bytes, thus 4 lines for 128,
161 8 lines for 256.  If we waste 8 bytes at the end, we have 8 lines
162 and 512 bytes encoded, the last line will be short by 16 characters,
163 so that the actual size on disk is 512 bytes.
164 .PP
165 Timestamps are 8 byte little endian integers of seconds since the epoch.  or
166 unix time, or some such.  Times are a mess.  Unix time is leap second unaware,
167 and ambiguous during leap seconds.  UTC requires a database of leap seconds for
168 past time, and the specified second in the future possibly changes.  TAI is
169 good, but currently 37 seconds behind UTC, which is just weird.
170 .PP
171 All key and signature data begin with an 8 byte header, consisting of
172 the following:
173 .EX
174 5A 50 4D 53 = "ZPMS" in ascii.
175 01          = one byte version number
176 xx          = one byte packet type
177 xx xx       = two bytes packet information
178 .EE
179 .PP
180 There are the following packet types.
181 .SS Private Keys
182 The public key is derivable from the secret key, so the public key is not
183 explicitly stored.
184 .EX
185 private key format is:
186 "ZPMS" 4 byte magic "ZPMS"
187 byte 0x01 = version 1
188 byte 0x01 = private key
189 byte 0x01 = chacha encrypted, 0x00 = plain/raw key bytes
190 byte 0x00 reserved, probably "key usage"
191 32 bytes private key
192 8 bytes creation time, little endian
193 8 bytes expiration time, little endian
194 8 bytes password salt, note, nist wants 16, but we're not using nist
195 approved hash algorithms anyway.
196 64 bytes reserved
197 could have 16 bytes of IV for chacha to encrypt.
198 Can probably use those, hashed with the password as the salt, but
199 not very much salt then.
200 120 bytes id
201 8 bytes reserved trailer
202 .EE
203 .SS Public Keys
204 .EX
205 public key format is:
206 "ZPMS" 4 byte magic "ZPMS"
207 0x01   1 byte version
208 0x02   1 byte "public key packet"
209 0x00   1 byte reserved
210 0x00   1 byte reserved
211 0x..  32 bytes public key
212 0x..  24 bytes reserved : create, expire, 8 reserved
213 0x..  64 bytes reserved : self sig
214      120 bytes reserved : id = 1 byte id length, n bytes id, zeros
215        8 bytes reserved trailer
216 0x..     revocation signatures
217 0x..     user id packets
218 0x..     certification signatures
219 0x..     sub key packets
220 .EE
221 .SS Signatures
222 Data, Key, and Revocation signatures all have the same format,
223 with the exception of the packet type byte at offset 5.  Type
224 0x03 is a data signature used for signing arbitrary data.  Type
225 0x04 is a key signature used to sign public keys.  Type 0x05 is
226 a revocation signature, used to revoke signatures.
227 .EX
228 "ZPMS" 4 byte magic "ZPMS"
229 0x01   1 byte version
230 0x03   1 byte "signature packet"
231 0x00   1 byte reserved
232 0x00   1 byte reserved
233 0x..   8 bytes timestamp of signature time
234 0x..   8 bytes timestamp of signature expiration, 0 if none
235 0x..  64 bytes of actual signature
236 0x..  32 bytes of public key making the signature
237 0x..   8 bytes reserved
238      120 bytes reserved
239        8 bytes reserved trailer
240 .EE
241 .SH EXAMPLES
242 .TP
243 .B zpm sign -s \fIpath\fR
244 Sign the contents of the file found at \fIpath\fR using the default secret key
245 with a signing timestamp of the current time and no expiration date.  The
246 signature packet will be written to stdout.
247 .TP
248 .B zpm sign -s -m 'foo'
249 Sign the string 'foo'.
250 .TP
251 .B printf '%s' foo | zpm sign -s
252 Sign the string 'foo' as in the above example, the message being read
253 from stdin.
254 .TP
255 .B zpm sign -s -r -m 'foo'
256 Sign the string 'foo' directly using the default private key, no
257 additional information is signed, and the output is a hex encoded
258 raw signature with no additional newlines, making up 128 characters
259 of output.  There is no way to output just the raw signature while
260 still adding the timestamps and such, but the raw signature can be
261 extracted from a signature packet.
262 .TP
263 .B zpm sign -s -r \\
264 -I 'c5aa8df43f9f837bedb7442f31dcb7b166d38535076f094b85ce3a2e0b4458f7' \\
265 -h -m 'af82'
266 Sign the two byte hex encoded message af82 with the raw hex encoded
267 secret key given by the -I argument.  The result will be
268 6291d657deec24024827e69c3abe01a30ce548a284743a445e3680d7db5ac3ac
269 18ff9b538d16f290ae67f760984dc6594a7c15e9716ed28dc027beceea1ec40a
270 all on a single line with no trailing newline.
271 .SH EXIT STATUS
272 0 on success non zero on failure
273 .SH BUGS
274 .PP
275 Timestamps are a mess.  Unix time is leap second unaware, and ambiguous during
276 leap seconds.  UTC requires a database of leap seconds for past time, and the
277 specified second in the future possibly changes.  TAI is good, but currently 37
278 seconds behind UTC, which is just weird.  Regardless of the above, unix
279 time was chosen for general compatibility with time functions.
280 .PP
281 There is no binding of a notion of an identity to a public key.
282 .PP
283 There is no trust level of a public key.  A reserved byte could be
284 used for this, but the semantics then need to be designed.
285 .SH NOTES ON CRYPTOGRAPHY
286 The general methods described by SEC 1 Ver 2.0 were followed, but
287 this is not an implementation of that scheme, because different
288 algorithms are used.
289 .PP
290 Chacha20 is used to encrypt private keys.
291 .SH FILES
292 ~/.zpm/keys
293 /var/lib/zpm/keys
294 .SH ENVIRONMENT
295 ZPM_KEYRING
296 .SH AUTHOR
297 Nathan Wagner
298 .SH SEE ALSO
299 .BR zpm (8)
300 .R RFC 
301 .R http://www.secg.org SEC 1 Ver 2.0