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