052b36d0 |
1 | /* -*-c-*- |
2 | * |
b817bfc6 |
3 | * $Id: key-data.h,v 1.4 2004/04/08 01:36:15 mdw Exp $ |
052b36d0 |
4 | * |
5 | * Manipulating key data |
6 | * |
7 | * (c) 1999 Straylight/Edgeware |
8 | */ |
9 | |
10 | /*----- Licensing notice --------------------------------------------------* |
11 | * |
12 | * This file is part of Catacomb. |
13 | * |
14 | * Catacomb is free software; you can redistribute it and/or modify |
15 | * it under the terms of the GNU Library General Public License as |
16 | * published by the Free Software Foundation; either version 2 of the |
17 | * License, or (at your option) any later version. |
18 | * |
19 | * Catacomb is distributed in the hope that it will be useful, |
20 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
21 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
22 | * GNU Library General Public License for more details. |
23 | * |
24 | * You should have received a copy of the GNU Library General Public |
25 | * License along with Catacomb; if not, write to the Free |
26 | * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, |
27 | * MA 02111-1307, USA. |
28 | */ |
29 | |
052b36d0 |
30 | #ifndef CATACOMB_KEY_DATA_H |
31 | #define CATACOMB_KEY_DATA_H |
32 | |
33 | #ifdef __cplusplus |
34 | extern "C" { |
35 | #endif |
36 | |
37 | /*----- Header files ------------------------------------------------------*/ |
38 | |
39 | #include <stddef.h> |
40 | |
41 | #include <mLib/bits.h> |
42 | #include <mLib/dstr.h> |
43 | #include <mLib/sym.h> |
44 | |
45 | #ifndef CATACOMB_MP_H |
46 | # include "mp.h" |
47 | #endif |
48 | |
1ba83484 |
49 | #ifndef CATACOMB_EC_H |
50 | # include "ec.h" |
51 | #endif |
52 | |
052b36d0 |
53 | /*----- Data structures ---------------------------------------------------*/ |
54 | |
55 | /* --- Key binary data --- */ |
56 | |
57 | typedef struct key_bin { |
58 | octet *k; /* Pointer to key data */ |
59 | size_t sz; /* Size of the key data (in bytes) */ |
60 | } key_bin; |
61 | |
62 | /* --- Key data structure --- */ |
63 | |
64 | typedef struct key_data { |
65 | unsigned e; /* Encoding type for key data */ |
66 | union { |
67 | key_bin k; /* Binary key data */ |
68 | mp *m; /* Multiprecision integer */ |
69 | sym_table s; /* Structured key data */ |
1ba83484 |
70 | char *p; /* String pointer */ |
71 | ec e; /* Elliptic curve point */ |
052b36d0 |
72 | } u; |
73 | } key_data; |
74 | |
75 | typedef struct key_struct { |
76 | sym_base _b; |
77 | key_data k; |
78 | } key_struct; |
79 | |
3f6ded6a |
80 | /* --- Packing and unpacking --- */ |
81 | |
82 | typedef struct key_packdef { |
83 | void *p; /* Pointer to the destination */ |
84 | key_data kd; /* Key data block */ |
85 | } key_packdef; |
86 | |
87 | typedef struct key_packstruct { |
88 | char *name; /* Pointer to name string */ |
89 | key_packdef kp; /* Packing structure */ |
90 | } key_packstruct; |
91 | |
052b36d0 |
92 | /* --- Key binary encoding --- * |
93 | * |
94 | * The binary encoding consists of a header containing a 16-bit encoding type |
95 | * and a 16-bit length, followed immediately by the key data, followed by |
96 | * between zero and three zero bytes to make the total length a multiple of |
97 | * four. The format of the following data depends on the encoding type: |
98 | * |
99 | * @KENC_BINARY@ Binary data. |
100 | * |
101 | * @KENC_MP@ Octet array interpreted in big-endian byte order. |
102 | * |
103 | * @KENC_STRUCT@ An array of pairs, each containing a string (8-bit |
104 | * length followed by data and zero-padding to 4-byte |
105 | * boundary) and key binary encodings. |
106 | * |
107 | * @KENC_ENCRYPT@ Binary data, format |
108 | */ |
109 | |
110 | /* --- Key encoding methods and other flags--- */ |
111 | |
112 | enum { |
113 | |
114 | /* --- Bottom two bits are the encoding type --- */ |
115 | |
1ba83484 |
116 | KF_ENCMASK = 0x83, /* Encoding mask */ |
052b36d0 |
117 | KENC_BINARY = 0x00, /* Plain binary key (@k@) */ |
118 | KENC_MP = 0x01, /* Multiprecision integer (@i@) */ |
119 | KENC_STRUCT = 0x02, /* Structured key data (@s@) */ |
120 | KENC_ENCRYPT = 0x03, /* Encrypted key type (@k@) */ |
1ba83484 |
121 | KENC_STRING = 0x80, /* ASCII string (@p@) */ |
122 | KENC_EC = 0x81, /* Elliptic curve point (@e@) */ |
052b36d0 |
123 | |
124 | /* --- Key category bits --- */ |
125 | |
126 | KF_CATMASK = 0x0c, /* Category mask */ |
127 | KCAT_SYMM = 0x00, /* Symmetric encryption key */ |
128 | KCAT_PRIV = 0x04, /* Private (asymmetric) key */ |
129 | KCAT_PUB = 0x08, /* Public (asymmetric) key */ |
130 | KCAT_SHARE = 0x0c, /* Shared (asymmetric) key */ |
131 | KF_NONSECRET = 0x08, /* Bit flag for non-secret keys */ |
132 | |
133 | /* --- Other flags --- */ |
134 | |
135 | KF_BURN = 0x10, /* Burn key after use */ |
136 | KF_TEMP = 0x20, /* Temporary copy flag */ |
3f6ded6a |
137 | KF_OPT = 0x40, /* Optional key (for @key_unpack@) */ |
052b36d0 |
138 | |
139 | /* --- Tag end --- */ |
140 | |
141 | KENC_MAX /* Dummy limit constant */ |
142 | }; |
143 | |
144 | /* --- Key flag filtering --- */ |
145 | |
146 | typedef struct key_filter { |
147 | unsigned f; |
148 | unsigned m; |
149 | } key_filter; |
150 | |
151 | /* --- Matching aginst key selection --- */ |
152 | |
153 | #define KEY_MATCH(kd, kf) \ |
154 | (!(kf) || \ |
155 | ((kd)->e & KF_ENCMASK) == KENC_STRUCT || \ |
156 | ((kd)->e & (kf)->m) == (kf)->f) |
157 | |
158 | /*----- Key flags and filtering -------------------------------------------*/ |
159 | |
160 | /* --- @key_readflags@ --- * |
161 | * |
162 | * Arguments: @const char *p@ = pointer to string to read |
163 | * @char **pp@ = where to store the end pointer |
164 | * @unsigned *ff@ = where to store the flags |
165 | * @unsigned *mm@ = where to store the mask |
166 | * |
167 | * Returns: Zero if all went well, nonzero if there was an error. |
168 | * |
169 | * Use: Reads a flag string. |
170 | */ |
171 | |
172 | extern int key_readflags(const char */*p*/, char **/*pp*/, |
173 | unsigned */*ff*/, unsigned */*mm*/); |
174 | |
175 | /* --- @key_writeflags@ --- * |
176 | * |
177 | * Arguments: @unsigned f@ = flags to write |
178 | * @dstr *d@ = pointer to destination string |
179 | * |
180 | * Returns: --- |
181 | * |
182 | * Use: Emits a flags word as a string representation. |
183 | */ |
184 | |
185 | extern void key_writeflags(unsigned /*f*/, dstr */*d*/); |
186 | |
187 | /* --- @key_match@ --- * |
188 | * |
189 | * Arguments: @key_data *k@ = pointer to key data block |
190 | * @const key_filter *kf@ = pointer to filter block |
191 | * |
192 | * Returns: Nonzero if the key matches the filter. |
193 | * |
194 | * Use: Checks whether a key matches a filter. |
195 | */ |
196 | |
197 | extern int key_match(key_data */*k*/, const key_filter */*kf*/); |
198 | |
199 | /*----- Setting new key data ----------------------------------------------*/ |
200 | |
201 | /* --- @key_binary@ --- * |
202 | * |
203 | * Arguments: @key_data *k@ = pointer to key data block |
204 | * @const void *p@ = pointer to key data |
205 | * @size_t sz@ = size of the key data |
206 | * |
207 | * Returns: --- |
208 | * |
209 | * Use: Sets a binary key in a key data block. |
210 | */ |
211 | |
212 | extern void key_binary(key_data */*k*/, const void */*p*/, size_t /*sz*/); |
213 | |
214 | /* --- @key_encrypted@ --- * |
215 | * |
216 | * Arguments: @key_data *k@ = pointer to key data block |
217 | * @const void *p@ = pointer to key data |
218 | * @size_t sz@ = size of the key data |
219 | * |
220 | * Returns: --- |
221 | * |
222 | * Use: Sets an encrypted key in a key data block. |
223 | */ |
224 | |
225 | extern void key_encrypted(key_data */*k*/, const void */*p*/, size_t /*sz*/); |
226 | |
227 | /* --- @key_mp@ --- * |
228 | * |
229 | * Arguments: @key_data *k@ = pointer to key data block |
230 | * @mp *m@ = pointer to the value to set |
231 | * |
232 | * Returns: --- |
233 | * |
234 | * Use: Sets a multiprecision integer key in a key block. |
235 | */ |
236 | |
237 | extern void key_mp(key_data */*k*/, mp */*m*/); |
238 | |
1ba83484 |
239 | /* --- @key_string@ --- * |
240 | * |
241 | * Arguments: @key_data *k@ = pointer to key data block |
242 | * @const char *p@ = pointer to the value to set |
243 | * |
244 | * Returns: --- |
245 | * |
246 | * Use: Sets a plain string in a key block. |
247 | */ |
248 | |
249 | extern void key_string(key_data */*k*/, const char */*p*/); |
250 | |
251 | /* --- @key_ec@ --- * |
252 | * |
253 | * Arguments: @key_data *k@ = pointer to key data block |
254 | * @const ec *e@ = pointer to the value to set |
255 | * |
256 | * Returns: --- |
257 | * |
258 | * Use: Sets an elliptic curve point in a key block. |
259 | */ |
260 | |
261 | extern void key_ec(key_data */*k*/, const ec */*e*/); |
262 | |
052b36d0 |
263 | /* --- @key_structure@ --- * |
264 | * |
265 | * Arguments: @key_data *k@ = pointer to key data block |
266 | * |
267 | * Returns: --- |
268 | * |
269 | * Use: Initializes a structured key type. |
270 | */ |
271 | |
272 | extern void key_structure(key_data */*k*/); |
273 | |
274 | /* --- @key_structfind@ --- * |
275 | * |
276 | * Arguments: @key_data *k@ = pointer to key data block |
277 | * @const char *tag@ = pointer to tag string |
278 | * |
279 | * Returns: Pointer to key data block, or null. |
280 | * |
281 | * Use: Looks up the tag in a structured key. |
282 | */ |
283 | |
284 | extern key_data *key_structfind(key_data */*k*/, const char */*tag*/); |
285 | |
286 | /* --- @key_structcreate@ --- * |
287 | * |
288 | * Arguments: @key_data *k@ = pointer to key data block |
289 | * @const char *tag@ = pointer to tag string |
290 | * |
291 | * Returns: Pointer to newly created key data. |
292 | * |
293 | * Use: Creates a new uninitialized subkey. |
294 | */ |
295 | |
296 | extern key_data *key_structcreate(key_data */*k*/, const char */*tag*/); |
297 | |
298 | /*----- Miscellaneous operations ------------------------------------------*/ |
299 | |
300 | /* --- @key_destroy@ --- * |
301 | * |
302 | * Arguments: @key_data *k@ = pointer to key data to destroy |
303 | * |
304 | * Returns: --- |
305 | * |
306 | * Use: Destroys a lump of key data. |
307 | */ |
308 | |
309 | extern void key_destroy(key_data */*k*/); |
310 | |
311 | /* --- @key_do@ --- * |
312 | * |
313 | * Arguments: @key_data *k@ = pointer to key data block |
314 | * @const key_filter *kf@ = pointer to filter block |
315 | * @dstr *d@ = pointer to base string |
316 | * @int (*func)(key_data *kd, dstr *d, void *p@ = function |
317 | * @void *p@ = argument to function |
318 | * |
319 | * Returns: Nonzero return code from function, or zero. |
320 | * |
321 | * Use: Runs a function over all the leaves of a key. |
322 | */ |
323 | |
324 | extern int key_do(key_data */*k*/, const key_filter */*kf*/, dstr */*d*/, |
325 | int (*/*func*/)(key_data */*kd*/, |
326 | dstr */*d*/, void */*p*/), |
327 | void */*p*/); |
328 | |
329 | /* --- @key_copy@ --- * |
330 | * |
331 | * Arguments: @key_data *kd@ = pointer to destination data block |
332 | * @key_data *k@ = pointer to source data block |
333 | * @const key_filter *kf@ = pointer to filter block |
334 | * |
335 | * Returns: Nonzero if an item was actually copied. |
336 | * |
337 | * Use: Copies a chunk of key data from one place to another. |
338 | */ |
339 | |
340 | extern int key_copy(key_data */*kd*/, key_data */*k*/, |
341 | const key_filter */*kf*/); |
342 | |
343 | /*----- Textual encoding --------------------------------------------------*/ |
344 | |
345 | /* --- @key_read@ --- * |
346 | * |
347 | * Arguments: @const char *p@ = pointer to textual key representation |
348 | * @key_data *k@ = pointer to output block for key data |
349 | * @char **pp@ = where to store the end pointer |
350 | * |
351 | * Returns: Zero if all went well, nonzero if there was a problem. |
352 | * |
353 | * Use: Parses a textual key description. |
354 | */ |
355 | |
356 | extern int key_read(const char */*p*/, key_data */*k*/, char **/*pp*/); |
357 | |
358 | /* --- @key_write@ --- * |
359 | * |
360 | * Arguments: @key_data *k@ = pointer to key data |
361 | * @dstr *d@ = destination string to write on |
362 | * @const key_filter *kf@ = pointer to key selection block |
363 | * |
364 | * Returns: Nonzero if any items were actually written. |
365 | * |
366 | * Use: Writes a key in a textual encoding. |
367 | */ |
368 | |
369 | extern int key_write(key_data */*k*/, dstr */*d*/, |
370 | const key_filter */*kf*/); |
371 | |
372 | /*----- Key binary encoding -----------------------------------------------*/ |
373 | |
374 | /* --- @key_decode@ --- * |
375 | * |
376 | * Arguments: @const void *p@ = pointer to buffer to read |
377 | * @size_t sz@ = size of the buffer |
378 | * @key_data *k@ = pointer to key data block to write to |
379 | * |
380 | * Returns: Zero if everything worked, nonzero otherwise. |
381 | * |
382 | * Use: Decodes a binary representation of a key. |
383 | */ |
384 | |
385 | extern int key_decode(const void */*p*/, size_t /*sz*/, key_data */*k*/); |
386 | |
387 | /* --- @key_encode@ --- * |
388 | * |
389 | * Arguments: @key_data *k@ = pointer to key data block |
390 | * @dstr *d@ = pointer to destination string |
391 | * @const key_filter *kf@ = pointer to key selection block |
392 | * |
393 | * Returns: Nonzero if any items were actually written. |
394 | * |
395 | * Use: Encodes a key block as binary data. |
396 | */ |
397 | |
398 | extern int key_encode(key_data */*k*/, dstr */*d*/, |
399 | const key_filter */*kf*/); |
400 | |
3f6ded6a |
401 | /*----- Packing and unpacking keys ----------------------------------------*/ |
402 | |
403 | /* --- @key_pack@ --- * |
404 | * |
405 | * Arguments: @key_packdef *kp@ = pointer to packing structure |
406 | * @key_data *kd@ = pointer to destination key data |
407 | * @dstr *d@ = pointer to tag string for the key data |
408 | * |
409 | * Returns: Error code, or zero. |
410 | * |
411 | * Use: Packs a key from a data structure. |
412 | */ |
413 | |
414 | extern int key_pack(key_packdef */*kp*/, key_data */*kd*/, dstr */*d*/); |
415 | |
416 | /* --- @key_unpack@ --- * |
417 | * |
418 | * Arguments: @key_packdef *kp@ = pointer to packing structure |
419 | * @key_data *kd@ = pointer to source key data |
420 | * @dstr *d@ = pointer to tag string for the key data |
421 | * |
422 | * Returns: Error code, or zero. |
423 | * |
424 | * Use: Unpacks a key into an appropriate data structure. |
425 | */ |
426 | |
427 | extern int key_unpack(key_packdef */*kp*/, key_data */*kd*/, dstr */*d*/); |
428 | |
429 | /* --- @key_unpackdone@ --- * |
430 | * |
431 | * Arguments: @key_packdef *kp@ = pointer to packing definition |
432 | * |
433 | * Returns: --- |
434 | * |
435 | * Use: Frees the key components contained within a packing |
436 | * definition, created during key unpacking. |
437 | */ |
438 | |
439 | extern void key_unpackdone(key_packdef */*kp*/); |
440 | |
052b36d0 |
441 | /*----- Passphrase encryption ---------------------------------------------*/ |
442 | |
443 | /* --- @key_plock@ --- * |
444 | * |
445 | * Arguments: @const char *tag@ = tag to use for passphrase |
446 | * @key_data *k@ = source key data block |
447 | * @key_data *kt@ = target key data block |
448 | * |
449 | * Returns: Zero if successful, nonzero if there was a problem. |
450 | * |
451 | * Use: Locks a key by encrypting it with a passphrase. |
452 | */ |
453 | |
454 | extern int key_plock(const char */*tag*/, key_data */*k*/, key_data */*kt*/); |
455 | |
456 | /* --- @key_punlock@ --- * |
457 | * |
458 | * Arguments: @const char *tag@ = tag to use for passphrase |
459 | * @key_data *k@ = source key data block |
460 | * @key_data *kt@ = target key data block |
461 | * |
462 | * Returns: Zero if it worked, nonzero if it didn't. |
463 | * |
464 | * Use: Unlocks a passphrase-locked key. |
465 | */ |
466 | |
467 | extern int key_punlock(const char */*tag*/, |
468 | key_data */*k*/, key_data */*kt*/); |
469 | |
470 | /*----- That's all, folks -------------------------------------------------*/ |
471 | |
472 | #ifdef __cplusplus |
473 | } |
474 | #endif |
475 | |
476 | #endif |