Commit | Line | Data |
---|---|---|
cb4edb9f | 1 | '\" e |
247f344a MW |
2 | .\" -*-nroff-*- |
3 | .EQ | |
4 | delim $$ | |
5 | .EN | |
6 | .de hP | |
7 | .IP | |
8 | \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c | |
9 | .. | |
10 | .ie t .ds o \(bu | |
11 | .el .ds o o | |
12 | .ds DH Diffie\(enHellman | |
13 | .TH udpkey 1 "2012-05-08" "Mark Wooding" "distorted.org.uk tools" | |
14 | .SH NAME | |
15 | udpkey \- send or receive a cryptographic key via a simple UDP protocol | |
16 | .SH SYNOPSIS | |
17 | .B udpkey | |
18 | .RB [ \-k | |
19 | .IR keyring ] | |
20 | .RB [ \-r | |
21 | .IR seed-file ] | |
22 | .I fragment-tag | |
23 | .I source-spec | |
24 | \&... | |
25 | .br | |
26 | .B udpkey | |
27 | .B \-l | |
28 | .RB [ \-d ] | |
29 | .RB [ \-k | |
30 | .IR keyring ] | |
31 | .RB [ \-r | |
32 | .IR seed-file ] | |
33 | .RI [ address \c | |
34 | .BR : ] \c | |
35 | .I port | |
36 | .PP | |
37 | .IR source-spec : | |
38 | .br | |
39 | ||
40 | .IB address : port \c | |
4efa5091 MW |
41 | .RB [ ? \c |
42 | .IR proto ] \c | |
581ea5da | 43 | .RB [ = \c |
247f344a | 44 | .IR tag ] \c |
581ea5da | 45 | .RB [ # \c |
247f344a MW |
46 | .IR hash ] \c |
47 | .BR ; ... | |
48 | .br | |
49 | ||
50 | .BI / filename | |
51 | | | |
52 | .BI ./ filename | |
53 | .SH DESCRIPTION | |
54 | The | |
55 | .B udpkey | |
56 | program can run in one of two modes: either it will request fragments of | |
57 | a key from a number of sources (e.g., local files or remote servers), | |
58 | assemble them together, and write the result to standard output; or it | |
59 | will listen on a UDP port and transmit encrypted copies of key fragments | |
60 | when requested. | |
61 | .PP | |
62 | The intended use of | |
63 | .B udpkey | |
64 | is for obtaining keys early in a system's boot process, so as to decrypt | |
65 | the main disk volumes. See the discussion below regarding the security | |
66 | properties of this approach. | |
67 | .SS Options | |
68 | The recognized command-line options are listed below. The synopsis | |
69 | shows two distinct invocations for clarity: in fact, all options are | |
70 | recognized all of the time, though options which are irrelevent in the | |
71 | chosen mode are silently ignored. | |
72 | .TP | |
73 | .B \-h, \-\-help | |
74 | Print a help message to standard output and exit successfully. | |
75 | .TP | |
76 | .B \-v, \-\-version | |
77 | Print the program's version number to standard output and exit | |
78 | successfully. | |
79 | .TP | |
80 | .B \-u, \-\-usage | |
81 | Print a brief usage summary to standard output and exit successfully. | |
82 | .TP | |
83 | .B \-d, \-\-daemon | |
84 | If the | |
85 | .B \-l | |
86 | option is also given, | |
87 | .B udpkey | |
88 | will detach from the terminal and run in the background after | |
89 | initialization. Also, it will write messages using | |
90 | .BR syslog (3) | |
91 | (with facility | |
92 | .BR daemon ) | |
93 | rather than to standard error. | |
94 | .TP | |
95 | .BI "\-k, \-\-keyring=" keyring | |
96 | Read keys from the | |
97 | .I keyring | |
98 | file, rather than the default, which is the file named | |
99 | .B keyring | |
100 | in the current working directory. | |
101 | .TP | |
102 | .B \-l, \-\-listen | |
103 | Listen for incoming requests for key fragments and reply to them. The | |
104 | default is to request key fragments. | |
105 | .TP | |
8d34ef00 | 106 | .BI "\-r, \-\-random=" seed-file |
247f344a MW |
107 | Use (an initial portion of) the contents of |
108 | .I seed-file | |
109 | to key the program's pseurorandom number generator. Since | |
110 | .B udpkey | |
111 | is intended to run early in a system's boot procedure, it's quite | |
112 | unlikely that there's a great deal of high-quality entropy available. | |
8d34ef00 MW |
113 | It's therefore useful to generate a seed while the system is running, |
114 | and store it somewhere where it can be found during early boot. | |
247f344a MW |
115 | .SS Client operation |
116 | For each | |
117 | .I source-spec | |
118 | on the command line of the form | |
119 | .BI / filename | |
120 | or | |
121 | .BI ./ filename | |
122 | the contents (or the inital 64KB of the contents, if the file is longer) | |
123 | are read as a key fragment. | |
124 | .PP | |
125 | For each | |
126 | .I source-spec | |
127 | of the form | |
128 | .IP | |
129 | .IB address : port \c | |
336b3767 | 130 | .RB [ = \c |
247f344a | 131 | .IR tag ] \c |
336b3767 | 132 | .RB [ # \c |
247f344a MW |
133 | .IR hash ] \c |
134 | .BR ; ... | |
135 | .PP | |
136 | a packet is sent to each listed | |
137 | .I address | |
138 | and | |
139 | .I port | |
140 | requesting the key fragment named by | |
141 | .IR fragment-tag ; | |
142 | responses are decrypted using the key | |
143 | .I tag | |
144 | (default | |
145 | .BR udpkey-kem ). | |
146 | If a valid response is received from any of the listed servers (matching | |
147 | the given | |
148 | .I hash | |
149 | if specified) then the contents are used as the key fragment; if no | |
150 | response is forthcoming from any of them then the requests are | |
151 | retransmitted periodically. If no acceptable reponse is received after | |
152 | a number of retransmissions, | |
153 | .B udpkey | |
154 | will give up. | |
155 | .PP | |
156 | If all of the fragments are successfully obtained then | |
157 | .B udpkey | |
158 | will check that they are the same length, XOR them together, and write | |
159 | the result to its standard output; it finally exits with status 0. | |
160 | .SS Server operaton | |
161 | If the | |
162 | .B \-l | |
163 | option was given, | |
164 | .B udpkey | |
165 | runs in sever mode. It listens for incoming UDP packets addressed to | |
166 | the given | |
167 | .I port | |
168 | (and, if specified, the given | |
169 | .I address | |
170 | \(en by default, any local address will do). If the | |
171 | .B \-d | |
172 | option was given, then | |
173 | .B udpkey | |
174 | will detach from its terminal (if any) and continue running in the | |
175 | background. | |
176 | .PP | |
177 | A request packet contains a key tag identifying the wanted key | |
178 | fragment. The key fragment is located. If the key data is not a plain | |
179 | binary string, or the key has no | |
180 | .B clients | |
8d34ef00 | 181 | attribute, then the request is rejected. Otherwise, the value of the |
247f344a MW |
182 | .B clients |
183 | attribute is expected to take the form | |
184 | .IP | |
185 | .IR address \c | |
186 | .RB [ / \c | |
187 | .IR prefix-len ] \c | |
188 | .RB [ = \c | |
189 | .IR tag ] \c | |
190 | .BR ; ... | |
191 | .PP | |
192 | The clauses of the attribute value are interpreted from left to right, | |
193 | as follows. If the most significant | |
194 | .I prefix-len | |
195 | bits (default 32 \(en i.e., all of them) of client's IP match the | |
196 | corresponding bits of | |
197 | .I address | |
198 | then send the key fragment, encrypted using the key named | |
199 | .I tag | |
200 | (default | |
201 | .BI client- addr \fR, | |
202 | where | |
203 | .I addr | |
204 | is the client's IP address in dotted-quad form); no further clauses are | |
205 | examined. If no clauses match then the request is refused and no reply | |
206 | is sent. | |
207 | .SS Key setup | |
208 | The | |
209 | .B udpkey | |
210 | program uses the Catacomb keyring format to store its cryptographic | |
211 | keys: see | |
212 | .BR keyring (5) | |
d07ca532 | 213 | for the technical details. Keys may be generated and managed using the |
247f344a MW |
214 | .BR key (1) |
215 | utility. | |
216 | .PP | |
217 | The security of | |
218 | .BR udpkey 's | |
219 | protocol (described below, for those who care about such things) is | |
8d34ef00 MW |
220 | based on the difficulty of \*(DH problems in cyclic groups. The client |
221 | needs to know the private key; the server need only know the public | |
222 | part. Both ends must agree on the attributes associated with the key. | |
247f344a MW |
223 | .PP |
224 | Two types of \*(DH groups are supported. The group type is determined | |
225 | from the appropriate key's | |
226 | .B group | |
227 | attribute, if present. The possible values are as follows. | |
228 | .TP | |
229 | .B dh | |
230 | Plain old \*(DH, in a Schnorr group \(en i.e., a prime-order subgroup of | |
8d34ef00 MW |
231 | the multiplicative group of a prime-order finite field. An appropriate |
232 | key may be generated using a command such as | |
247f344a MW |
233 | .RS |
234 | .IP | |
235 | .nf | |
236 | .BI "key add \-t" tag " \-adh \-LS \-b3072 \-B256 udpkey-kem group=dh \fR..." | |
237 | .fi | |
238 | .RE | |
239 | .TP | |
240 | .B ec | |
241 | A prime order subgroup of the group of projective points on an elliptic | |
242 | curve. Catacomb's | |
243 | .BR key (1) | |
244 | program can't generate such groups, though it knows of a number of | |
8d34ef00 MW |
245 | suitable examples, or you can use your own curves. An appropriate key |
246 | can be generated using a command such as | |
247f344a MW |
247 | .RS |
248 | .IP | |
249 | .BI "key add \-t" tag " \-aec \-Cnist-p256 udpkey-kem group=ec \fR..." | |
250 | .RE | |
251 | .PP | |
252 | Other attributes on the key determine the ancillary cryptographic | |
253 | algorithms used in the protocol, as follows. | |
254 | .TP | |
255 | .B hash | |
256 | The hash function used to derive symmetric keys from the shared secret | |
257 | group element. The default is | |
258 | .BR sha256 . | |
259 | .TP | |
260 | .B cipher | |
261 | The symmetric encryption algorithm used to encrypt the key fragment. | |
262 | The default is | |
263 | .BR rijndael-counter . | |
264 | .TP | |
265 | .B mac | |
266 | The message authentication code used to ensure the integrity of the | |
267 | ciphertext, in the form | |
d07ca532 MW |
268 | .IB name\fR[ / tagbits \fR]. |
269 | The defaults are to use HMAC with the chosen hash function, and truncate | |
247f344a MW |
270 | the tag to half of its original length. |
271 | .PP | |
272 | Key fragments must contain only plain binary data: you can generate one | |
273 | using a command such as | |
274 | .IP | |
275 | .BI "key add \-t" tag " \-abinary \-b256 udpkey-frag clients=" client-spec " \fR..." | |
276 | .PP | |
277 | The | |
278 | .B client | |
279 | attribute is mandatory; its syntax and semantics are described above. | |
280 | .SS Protocol description | |
281 | Let $G$ be a cyclic group with prime order $q$; we consider this as a | |
282 | one-dimensional vector space over the finite field ${roman GF}(q)$. Let | |
8d34ef00 | 283 | $P$ be any nonzero vector. |
247f344a MW |
284 | .PP |
285 | The client's private key is a scalar $x$; its public key is the | |
286 | corresponding vector $X = x P$. When constructing a request, a client | |
287 | selects a random scalar $u$; let $U = u P$ be the corresponding vector. | |
288 | The request packet consists of the key tag of the wanted key fragment | |
289 | followed by a representation of the vector $U$. | |
290 | .PP | |
291 | When constructing a response, a server selects random scalars $v$ and | |
8d34ef00 | 292 | $r$, and computes $V = v P$ and $R = r P$. It then determines $Y = v U$ |
247f344a MW |
293 | and $Z = r X$, and hashes $R$ and $Z$ to obtain keys for a symmetric |
294 | cipher and MAC. It encrypts the key fragment and authenticates the | |
295 | resulting ciphertext. Finally, the response consists of the vectors $V$ | |
296 | and $W = R - Y$, the MAC tag on the ciphertext, and the ciphertext | |
297 | itself. | |
298 | .PP | |
299 | The client can determine $Y = u V$, $R = W + Y$, and compute $Z = x R$, | |
300 | and thereby recover the cipher and MAC keys. | |
301 | .SS Security discussion | |
302 | We assume that the client can securely | |
303 | .I erase | |
304 | the key, and the ephemeral secret scalar $r$, from its memory once it | |
305 | has finished using them. If we detect that the client has compromised | |
306 | at some point when it does not know the key, we can instruct the servers | |
307 | to withhold their fragments of the key. | |
308 | .PP | |
309 | The dance with $U$ and $V$ is a standard ephemeral \*(DH key exchange. | |
310 | The other dance with $R$ and $X$, and the symmetric encryption, is | |
311 | basically DLIES. The only trick is that $R$ is masked in the reply | |
312 | using the ephemeral \*(DH key $Y$. (Subtracting rather than adding $Y$ | |
313 | is more efficient. For the server, it makes no difference, since it can | |
314 | compute $-Y = (-v) U$ and add; but for the client, subtraction might be | |
315 | rather slower than addition.) | |
316 | .PP | |
317 | We have the following properties. | |
318 | .hP \*o | |
319 | Passively collecting requests and responses before compromising the | |
320 | client does not assist an adversary in determining the value of a key | |
321 | fragment, since the ephemeral scalars $u$ and $v$ are random and | |
322 | independent. Assuming that Decisional \*(DH is hard in $G$, the | |
323 | ephemeral secret $Y$ appears random to the adversary, so $W$ leaks | |
324 | nothing about $R$. The symmetric keys are therefore independent of the | |
325 | adversary's view. | |
326 | .IP | |
327 | We can do better. Suppose that an adversary can recover the symmetric | |
328 | key given a request/reply pair. If we assume that the symmetric | |
329 | encryption is good, then the adversary must have found the key by | |
330 | hashing $R$ and $Z$. Therefore it can recover $Y = R - W$, which solves | |
331 | an instance of the harder | |
332 | .I Computational | |
8d34ef00 MW |
333 | (actually, Gap) \*(DH problem in $G$. |
334 | .IP | |
335 | This analysis can be made rigorous and quantitative. | |
247f344a MW |
336 | .hP \*o |
337 | Neither side attempts to authenticate the other explicitly. The server | |
338 | implicitly authenticates the client by encrypting its key fragment using | |
339 | the client's public key. (This encryption is standard DLIES, and | |
8d34ef00 | 340 | security again depends on the Gap \*(DH problem in $G$.) The client |
247f344a MW |
341 | doesn't attempt to authenticate the server at all, though it can check |
342 | that the response is correct by comparing its hash to a known copy; this | |
343 | confirms that the received key fragment is correct, and the client has | |
344 | no reason to care where a correct key fragment really came from. | |
345 | .hP \*o | |
346 | If multiple sources are used, and each knows a fragment chosen uniformly | |
347 | at random,, then none of the individual sources has enough information | |
348 | to construct the complete key. | |
349 | .hP \*o | |
350 | Storing a key fragment in a local file means that compromising servers | |
351 | doesn't help an adversary obtain the key: the client | |
352 | .I must | |
353 | be compromised if the adversary is to succeed. | |
354 | .hP \*o | |
355 | If the client is compromised, and none of the sources has revoked the | |
356 | client's access to its fragment, then the game is over and the adversary | |
357 | wins. The client can obviously decrypt the fragments and assemble | |
358 | them. If any source refuses to provide its fragment, the adversary | |
359 | learns nothing about the reassembled key. | |
360 | .hP \*o | |
361 | In practice, high quality entropy is probably in short supply during | |
362 | early boot. If an adversary can guess the ephemeral \*(DH scalar $u$ | |
363 | having compromised the client, he can potentially decrypt a previously | |
364 | captured response. Periodically rekeying the random number generator | |
365 | \(en by rewriting the | |
366 | .I seed-file | |
367 | when high-quality entropy is available \(en serves to limit the exposure | |
368 | to responses captured since the last rekeying. | |
369 | .SH BUGS | |
37b2b8ac | 370 | None known. |
247f344a MW |
371 | .SH SEE ALSO |
372 | .BR key (1), | |
373 | .BR crypttab (5), | |
374 | .BR keyring (5), | |
375 | .BR cryptsetup (8), | |
376 | .BR initramfs-tools (8). | |
377 | .SH AUTHOR | |
378 | Mark Wooding, <mdw@distorted.org.uk> |