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