X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/d11a0bf77a5230387d222ec727865a898767ff3e..1d6d3b01cb40e0cfaeb816c87c513695aea0816a:/key.h diff --git a/key.h b/key.h index 6a17ded..dffd0eb 100644 --- a/key.h +++ b/key.h @@ -1,13 +1,13 @@ /* -*-c-*- * - * $Id: key.h,v 1.3 1999/12/22 15:47:48 mdw Exp $ + * $Id$ * * Simple key management * * (c) 1999 Straylight/Edgeware */ -/*----- Licensing notice --------------------------------------------------* +/*----- Licensing notice --------------------------------------------------* * * This file is part of Catacomb. * @@ -15,32 +15,18 @@ * it under the terms of the GNU Library General Public License as * published by the Free Software Foundation; either version 2 of the * License, or (at your option) any later version. - * + * * Catacomb is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Library General Public License for more details. - * + * * You should have received a copy of the GNU Library General Public * License along with Catacomb; if not, write to the Free * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, * MA 02111-1307, USA. */ -/*----- Revision history --------------------------------------------------* - * - * $Log: key.h,v $ - * Revision 1.3 1999/12/22 15:47:48 mdw - * Major key-management revision. - * - * Revision 1.2 1999/12/10 23:29:48 mdw - * Change header file guard names. - * - * Revision 1.1 1999/09/03 08:41:12 mdw - * Initial import. - * - */ - #ifndef CATACOMB_KEY_H #define CATACOMB_KEY_H @@ -58,6 +44,18 @@ #include #include +#ifndef CATACOMB_KEY_ERROR_H +# include "key-error.h" +#endif + +#ifndef CATACOMB_KEY_DATA_H +# include "key-data.h" +#endif + +#ifndef CATACOMB_GHASH_H +# include "ghash.h" +#endif + #ifndef CATACOMB_MP_H # include "mp.h" #endif @@ -76,99 +74,6 @@ typedef struct key_attr { char *p; /* Pointer to attribute value */ } key_attr; -/* --- Key data structure --- */ - -typedef struct key_data { - unsigned e; /* Encoding type for key data */ - union { - - /* --- Plain binary key data --- * - * - * Also used for encrypted key types. - */ - - struct { - octet *k; /* Actual key data */ - size_t sz; /* Size of the key data */ - } k; /* Plain binary key */ - - /* --- Multiprecision integer keys --- */ - - mp *m; /* Multiprecision integer */ - - /* --- Structured key data --- */ - - sym_table s; /* Structured key data */ - } u; -} key_data; - -typedef struct key_struct { - sym_base _b; - key_data k; -} key_struct; - -/* --- Key binary encoding --- * - * - * The binary encoding consists of a header containing a 16-bit encoding type - * and a 16-bit length, followed immediately by the key data, followed by - * between zero and three zero bytes to make the total length a multiple of - * four. The format of the following data depends on the encoding type: - * - * @KENC_BINARY@ Binary data. - * - * @KENC_MP@ Octet array interpreted in big-endian byte order. - * - * @KENC_STRUCT@ An array of pairs, each containing a string (8-bit - * length followed by data and zero-padding to 4-byte - * boundary) and key binary encodings. - * - * @KENC_ENCRYPT@ Binary data, format - */ - -/* --- Key encoding methods and other flags--- */ - -enum { - - /* --- Bottom two bits are the encoding type --- */ - - KF_ENCMASK = 0x03, /* Encoding mask */ - KENC_BINARY = 0x00, /* Plain binary key (@k@) */ - KENC_MP = 0x01, /* Multiprecision integer (@i@) */ - KENC_STRUCT = 0x02, /* Structured key data (@s@) */ - KENC_ENCRYPT = 0x03, /* Encrypted key type (@k@) */ - - /* --- Key category bits --- */ - - KF_CATMASK = 0x0c, /* Category mask */ - KCAT_SYMM = 0x00, /* Symmetric encryption key */ - KCAT_PRIV = 0x04, /* Private (asymmetric) key */ - KCAT_PUB = 0x08, /* Public (asymmetric) key */ - KCAT_SHARE = 0x0c, /* Shared (asymmetric) key */ - KF_NONSECRET = 0x08, /* Bit flag for non-secret keys */ - - /* --- Other flags --- */ - - KF_BURN = 0x10, /* Burn key after use */ - - /* --- Tag end --- */ - - KENC_MAX /* Dummy limit constant */ -}; - -/* --- Key flag filtering --- */ - -typedef struct key_filter { - unsigned f; - unsigned m; -} key_filter; - -/* --- Matching aginst key selection --- */ - -#define KEY_MATCH(kd, kf) \ - (!(kf) || \ - ((kd)->e & KF_ENCMASK) == KENC_STRUCT || \ - ((kd)->e & (kf)->m) == (kf)->f) - /* --- Main key structure --- * * * Each key is stored in two symbol tables, one indexed by keyid, and the @@ -179,7 +84,7 @@ typedef struct key_filter { typedef struct key { /* --- Hashtable management --- */ - + hash_base _b; /* Symbol table data */ struct key *next; /* Next key of the same type */ @@ -192,7 +97,7 @@ typedef struct key { /* --- The key data itself --- */ - key_data k; /* The actual key data */ + key_data *k; /* The actual key data */ /* --- Other attributes and commentary --- */ @@ -221,10 +126,8 @@ typedef struct key_file { /* --- Key file flags --- */ -enum { - KF_WRITE = 1, /* File opened for writing */ - KF_MODIFIED = 2 /* File has been modified */ -}; +#define KF_WRITE 1u /* File opened for writing */ +#define KF_MODIFIED 2u /* File has been modified */ /* --- Iterating over keys --- * * @@ -235,34 +138,27 @@ enum { typedef struct { hash_iter i; time_t t; } key_iter; typedef struct { sym_iter i; } key_attriter; +/* --- Key fetching --- */ + +typedef struct key_fetchdef { + char *name; /* Name of item */ + size_t off; /* Offset into target structure */ + unsigned e; /* Flags for the item */ + const struct key_fetchdef *kf; /* Substructure pointer */ +} key_fetchdef; + /* --- File opening options --- */ -enum { - KOPEN_READ, - KOPEN_WRITE -}; +#define KOPEN_READ 0u +#define KOPEN_WRITE 1u +#define KOPEN_MASK 0xff +#define KOPEN_NOFILE 0x100 /* --- Various other magic numbers --- */ #define KEXP_FOREVER ((time_t)-1) /* Never expire this key */ #define KEXP_EXPIRE ((time_t)-2) /* Expire this key when unused */ -/* --- Key error codes --- */ - -enum { - KERR_OK, /* No error */ - KERR_BADTAG = -1, /* Malformed tag string */ - KERR_BADTYPE = -2, /* Malformed type string */ - KERR_BADCOMMENT = -3, /* Malformed comment string */ - KERR_DUPID = -4, /* Duplicate keyid */ - KERR_DUPTAG = -5, /* Duplicate key tag string */ - KERR_READONLY = -6, /* Key file is read-only */ - KERR_WILLEXPIRE = -7, /* Key will eventually expire */ - KERR_EXPIRED = -8, /* Key has already expired */ - KERR_BADFLAGS = -9, /* Error in flags string */ - KERR_MAX /* Largest possible error */ -}; - /* --- Write error codes --- */ enum { @@ -281,244 +177,6 @@ typedef void key_reporter(const char */*file*/, int /*line*/, #define KEY_EXPIRED(now, exp) \ ((exp) == KEXP_EXPIRE || ((exp) != KEXP_FOREVER && (exp) < (now))) -/*----- Key data manipulation ---------------------------------------------*/ - -/* --- @key_destroy@ --- * - * - * Arguments: @key_data *k@ = pointer to key data to destroy - * - * Returns: --- - * - * Use: Destroys a lump of key data. - */ - -extern void key_destroy(key_data */*k*/); - -/* --- @key_readflags@ --- * - * - * Arguments: @const char *p@ = pointer to string to read - * @char **pp@ = where to store the end pointer - * @unsigned *ff@ = where to store the flags - * @unsigned *mm@ = where to store the mask - * - * Returns: Zero if all went well, nonzero if there was an error. - * - * Use: Reads a flag string. - */ - -extern int key_readflags(const char */*p*/, char **/*pp*/, - unsigned */*ff*/, unsigned */*mm*/); - -/* --- @key_writeflags@ --- * - * - * Arguments: @unsigned f@ = flags to write - * @dstr *d@ = pointer to destination string - * - * Returns: --- - * - * Use: Emits a flags word as a string representation. - */ - -extern void key_writeflags(unsigned /*f*/, dstr */*d*/); - -/* --- @key_binary@ --- * - * - * Arguments: @key_data *k@ = pointer to key data block - * @const void *p@ = pointer to key data - * @size_t sz@ = size of the key data - * - * Returns: --- - * - * Use: Sets a binary key in a key data block. - */ - -extern void key_binary(key_data */*k*/, const void */*p*/, size_t /*sz*/); - -/* --- @key_encrypted@ --- * - * - * Arguments: @key_data *k@ = pointer to key data block - * @const void *p@ = pointer to key data - * @size_t sz@ = size of the key data - * - * Returns: --- - * - * Use: Sets an encrypted key in a key data block. - */ - -extern void key_encrypted(key_data */*k*/, const void */*p*/, size_t /*sz*/); - -/* --- @key_mp@ --- * - * - * Arguments: @key_data *k@ = pointer to key data block - * @mp *m@ = pointer to the value to set - * - * Returns: --- - * - * Use: Sets a multiprecision integer key in a key block. - */ - -extern void key_mp(key_data */*k*/, mp */*m*/); - -/* --- @key_structure@ --- * - * - * Arguments: @key_data *k@ = pointer to key data block - * - * Returns: --- - * - * Use: Initializes a structured key type. - */ - -extern void key_structure(key_data */*k*/); - -/* --- @key_structfind@ --- * - * - * Arguments: @key_data *k@ = pointer to key data block - * @const char *tag@ = pointer to tag string - * - * Returns: Pointer to key data block, or null. - * - * Use: Looks up the tag in a structured key. - */ - -extern key_data *key_structfind(key_data */*k*/, const char */*tag*/); - -/* --- @key_structcreate@ --- * - * - * Arguments: @key_data *k@ = pointer to key data block - * @const char *tag@ = pointer to tag string - * - * Returns: Pointer to newly created key data. - * - * Use: Creates a new uninitialized subkey. - */ - -extern key_data *key_structcreate(key_data */*k*/, const char */*tag*/); - -/* --- @key_match@ --- * - * - * Arguments: @key_data *k@ = pointer to key data block - * @const key_filter *kf@ = pointer to filter block - * - * Returns: Nonzero if the key matches the filter. - * - * Use: Checks whether a key matches a filter. - */ - -extern int key_match(key_data */*k*/, const key_filter */*kf*/); - -/* --- @key_do@ --- * - * - * Arguments: @key_data *k@ = pointer to key data block - * @const key_filter *kf@ = pointer to filter block - * @dstr *d@ = pointer to base string - * @int (*func)(key_data *kd, dstr *d, void *p@ = function - * @void *p@ = argument to function - * - * Returns: Nonzero return code from function, or zero. - * - * Use: Runs a function over all the leaves of a key. - */ - -extern int key_do(key_data */*k*/, const key_filter */*kf*/, dstr */*d*/, - int (*/*func*/)(key_data */*kd*/, - dstr */*d*/, void */*p*/), - void */*p*/); - -/* --- @key_copy@ --- * - * - * Arguments: @key_data *kd@ = pointer to destination data block - * @key_data *k@ = pointer to source data block - * @const key_filter *kf@ = pointer to filter block - * - * Returns: Nonzero if an item was actually copied. - * - * Use: Copies a chunk of key data from one place to another. - */ - -extern int key_copy(key_data */*kd*/, key_data */*k*/, - const key_filter */*kf*/); - -/* --- @key_read@ --- * - * - * Arguments: @const char *p@ = pointer to textual key representation - * @key_data *k@ = pointer to output block for key data - * @char **pp@ = where to store the end pointer - * - * Returns: Zero if all went well, nonzero if there was a problem. - * - * Use: Parses a textual key description. - */ - -extern int key_read(const char */*p*/, key_data */*k*/, char **/*pp*/); - -/* --- @key_write@ --- * - * - * Arguments: @key_data *k@ = pointer to key data - * @dstr *d@ = destination string to write on - * @const key_filter *kf@ = pointer to key selection block - * - * Returns: Nonzero if any items were actually written. - * - * Use: Writes a key in a textual encoding. - */ - -extern int key_write(key_data */*k*/, dstr */*d*/, - const key_filter */*kf*/); - -/* --- @key_decode@ --- * - * - * Arguments: @const void *p@ = pointer to buffer to read - * @size_t sz@ = size of the buffer - * @key_data *k@ = pointer to key data block to write to - * - * Returns: Zero if everything worked, nonzero otherwise. - * - * Use: Decodes a binary representation of a key. - */ - -extern int key_decode(const void */*p*/, size_t /*sz*/, key_data */*k*/); - -/* --- @key_encode@ --- * - * - * Arguments: @key_data *k@ = pointer to key data block - * @dstr *d@ = pointer to destination string - * @const key_filter *kf@ = pointer to key selection block - * - * Returns: Nonzero if any items were actually written. - * - * Use: Encodes a key block as binary data. - */ - -extern int key_encode(key_data */*k*/, dstr */*d*/, - const key_filter */*kf*/); - -/* --- @key_plock@ --- * - * - * Arguments: @const char *tag@ = tag to use for passphrase - * @key_data *k@ = source key data block - * @key_data *kt@ = target key data block - * - * Returns: Zero if successful, nonzero if there was a problem. - * - * Use: Locks a key by encrypting it with a passphrase. - */ - -extern int key_plock(const char */*tag*/, key_data */*k*/, key_data */*kt*/); - -/* --- @key_punlock@ --- * - * - * Arguments: @const char *tag@ = tag to use for passphrase - * @key_data *k@ = source key data block - * @key_data *kt@ = target key data block - * - * Returns: Zero if it worked, nonzero if it didn't. - * - * Use: Unlocks a passphrase-locked key. - */ - -extern int key_punlock(const char */*tag*/, - key_data */*k*/, key_data */*kt*/); - /*----- Reading and writing keys and files --------------------------------*/ /* --- @key_merge@ --- * @@ -556,7 +214,7 @@ extern int key_extract(key_file */*f*/, key */*k*/, FILE */*fp*/, * * Arguments: @key_file *f@ = pointer to file structure to initialize * @const char *file@ = pointer to the file name - * @int how@ = opening options (@KOPEN_*@). + * @unsigned how@ = opening options (@KOPEN_*@). * @key_reporter *rep@ = error reporting function * @void *arg@ = argument for function * @@ -570,9 +228,20 @@ extern int key_extract(key_file */*f*/, key */*k*/, FILE */*fp*/, * owner only. */ -extern int key_open(key_file */*f*/, const char */*file*/, int /*how*/, +extern int key_open(key_file */*f*/, const char */*file*/, unsigned /*how*/, key_reporter */*rep*/, void */*arg*/); +/* --- @key_discard@ --- * + * + * Arguments: @key_file *f@ = pointer to key file block + * + * Returns: --- + * + * Use: Frees all the key data, without writing changes. + */ + +extern void key_discard(key_file */*f*/); + /* --- @key_close@ --- * * * Arguments: @key_file *f@ = pointer to key file block @@ -607,7 +276,7 @@ extern int key_save(key_file */*f*/); * * Arguments: @key_file *f@ = pointer to file structure to initialize * @const char *file@ = pointer to the file name - * @int how@ = opening options (@KOPEN_*@). + * @unsigned how@ = opening options (@KOPEN_*@). * * Returns: Zero if it worked, nonzero otherwise. * @@ -622,7 +291,8 @@ extern int key_save(key_file */*f*/); * for the private use of @key_open@. */ -extern int key_lockfile(key_file */*f*/, const char */*file*/, int /*how*/); +extern int key_lockfile(key_file */*f*/, const char */*file*/, + unsigned /*how*/); /*----- Creating and manipulating keys ------------------------------------*/ @@ -632,10 +302,9 @@ extern int key_lockfile(key_file */*f*/, const char */*file*/, int /*how*/); * @uint32 id@ = keyid to set * @const char *type@ = the type of this key * @time_t exp@ = when the key expires - * @int *err@ = where to store the error condition + * @key *kk@ = where to put the key pointer * - * Returns: Key block containing new data, or null if it couldn't be - * done. + * Returns: Error code (one of the @KERR@ constants). * * Use: Attaches a new key to a key file. You must have a writable * key file for this to work. @@ -654,8 +323,8 @@ extern int key_lockfile(key_file */*f*/, const char */*file*/, int /*how*/); * You have to set the actual key yourself. */ -extern key *key_new(key_file */*f*/, uint32 /*id*/, const char */*type*/, - time_t /*exp*/, int */*err*/); +extern int key_new(key_file */*f*/, uint32 /*id*/, const char */*type*/, + time_t /*exp*/, key **/*kk*/); /* --- @key_delete@ --- * * @@ -674,6 +343,15 @@ extern key *key_new(key_file */*f*/, uint32 /*id*/, const char */*type*/, extern int key_delete(key_file */*f*/, key */*k*/); +/* --- @key_expired@ --- * + * + * Arguments: @key *k@ = pointer to key block + * + * Returns: Zero if the key is OK, nonzero if it's expired. + */ + +int key_expired(key */*k*/); + /* --- @key_expire@ --- * * * Arguments: @key_file *f@ = pointer to file block @@ -708,6 +386,20 @@ extern int key_expire(key_file */*f*/, key */*k*/); extern int key_used(key_file */*f*/, key */*k*/, time_t /*t*/); +/* --- @key_fingerprint@ --- * + * + * Arguments: @key *k@ = the key to fingerprint + * @ghash *h@ = the hash to use + * @const key_filter *kf@ = filter to apply + * + * Returns: Nonzero if the key slightly matched the filter. + * + * Use: Updates the hash context with the key contents. + */ + +extern int key_fingerprint(key */*k*/, ghash */*h*/, + const key_filter */*kf*/); + /*----- Setting and reading attributes ------------------------------------*/ /* --- @key_chkident@ --- * @@ -758,6 +450,19 @@ extern int key_setcomment(key_file */*f*/, key */*k*/, const char */*c*/); extern int key_settag(key_file */*f*/, key */*k*/, const char */*tag*/); +/* --- @key_setkeydata@ --- * + * + * Arguments: @key_file *kf@ = pointer to key file + * @key *k@ = pointer to key + * @key_data *kd@ = new key data + * + * Returns: Zero on success, or a @KERR_@ error code on failure. + * + * Use: Sets the key data for a key. + */ + +extern int key_setkeydata(key_file */*kf*/, key */*k*/, key_data */*kd*/); + /* --- @key_fulltag@ --- * * * Arguments: @key *k@ = pointer to key @@ -778,7 +483,7 @@ extern void key_fulltag(key */*k*/, dstr */*d*/); * @const char *tag@ = pointer to tag string * @dstr *d@ = pointer to string for full tag name * @key **k@ = where to store the key pointer - * @key_data **kd@ = where to store the key data pointer + * @key_data ***kd@ = where to store the key data pointer * * Returns: Zero if OK, nonzero if it failed. * @@ -786,11 +491,11 @@ extern void key_fulltag(key */*k*/, dstr */*d*/); * qualified by the names of subkeys, separated by dots. Hence, * a qualified tag is ID|TAG[.TAG...]. The various result * pointers can be null to indicate that the result isn't - * interesting. + * interesting. */ extern int key_qtag(key_file */*f*/, const char */*tag*/, - dstr */*d*/, key **/*k*/, key_data **/*kd*/); + dstr */*d*/, key **/*k*/, key_data ***/*kd*/); /* --- @key_getattr@ --- * * @@ -914,6 +619,63 @@ extern void key_mkiter(key_iter */*i*/, key_file */*f*/); extern key *key_next(key_iter */*i*/); +/*----- Fetching key data conveniently ------------------------------------*/ + +/* --- @key_fetchinit@ --- * + * + * Arguments: @const key_fetchdef *kf@ = pointer to base definition + * @key_packstruct *kps@ = pointer to destination packing def + * @void *p@ = pointer to destination block + * + * Returns: Pointer to packing definition. + * + * Use: Initializes a packing definition (@key_packdef@ structure). + * If @kps@ is null on entry, an appropriately sized block is + * allocated automatically. Otherwise it must be large enough. + */ + +extern key_packdef *key_fetchinit(const key_fetchdef */*kf*/, + key_packstruct */*kp*/, void */*p*/); + +/* --- @key_fetch@ --- * + * + * Arguments: @key_packdef *kp@ = pointer to packing structure + * @key *k@ = key file containing desired key + * + * Returns: Error code, or zero. + * + * Use: Fetches an unpacked key from a packed one. + */ + +extern int key_fetch(key_packdef */*kp*/, key */*k*/); + +/* --- @key_fetchbyname@ --- * + * + * Arguments: @key_packdef *kp@ = pointer to packing structure + * @key_file *kf@ = key file containing desired key + * @const char *tag@ = user's tag describing the key + * + * Returns: Error code, or zero. + * + * Use: Fetches a named key from a key file and unpacks it + * conveniently. + */ + +extern int key_fetchbyname(key_packdef */*kp*/, + key_file */*kf*/, const char */*tag*/); + +/* --- @key_fetchdone@ --- * + * + * Arguments: @key_packdef *kp@ = pointer to packing structure + * + * Returns: --- + * + * Use: Frees a packing structure. If the structure was allocated by + * @key_fetchinit@ then it is freed. + */ + +extern void key_fetchdone(key_packdef */*kp*/); + /*----- Other functions ---------------------------------------------------*/ /* --- @key_moan@ --- * @@ -931,17 +693,6 @@ extern key *key_next(key_iter */*i*/); extern void key_moan(const char */*file*/, int /*line*/, const char */*msg*/, void */*p*/); -/* --- @key_strerror@ --- * - * - * Arguments: @int err@ = error code from @key_new@ - * - * Returns: Pointer to error string. - * - * Use: Translates a @KERR@ error code into a human-readable string. - */ - -extern const char *key_strerror(int /*err*/); - /*----- That's all, folks -------------------------------------------------*/ #ifdef __cplusplus