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