projects / u / mdw / catacomb / blob
? search:


4eb8845b5be3deda1aa0873cdf18622838d38792
[u/mdw/catacomb] / key-data.h
1 /* -*-c-*-
2 *
3 * $Id: key-data.h,v 1.3 2004/03/28 01:58:47 mdw Exp $
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 $
33 * Revision 1.3 2004/03/28 01:58:47 mdw
34 * Generate, store and retreive elliptic curve keys.
35 *
36 * Revision 1.2 2000/06/17 11:26:18 mdw
37 * Add the key packing interface.
38 *
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
63 #ifndef CATACOMB_EC_H
64 # include "ec.h"
65 #endif
66
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 */
84 char *p; /* String pointer */
85 ec e; /* Elliptic curve point */
86 } u;
87 } key_data;
88
89 typedef struct key_struct {
90 sym_base _b;
91 key_data k;
92 } key_struct;
93
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
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
130 KF_ENCMASK = 0x83, /* Encoding mask */
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@) */
135 KENC_STRING = 0x80, /* ASCII string (@p@) */
136 KENC_EC = 0x81, /* Elliptic curve point (@e@) */
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 */
151 KF_OPT = 0x40, /* Optional key (for @key_unpack@) */
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
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
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
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
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
Catacomb cryptographic library (downstream of http://git.distorted.org.uk/~mdw/catacomb/)