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