X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/b3f050848e5d285c2a1d7f8a4bea98984c201805..6ec3a4cf4aaa7cd375e1aa18f85861986259b8e5:/key.h diff --git a/key.h b/key.h index 3874f2c..dffd0eb 100644 --- a/key.h +++ b/key.h @@ -1,13 +1,13 @@ /* -*-c-*- * - * $Id: key.h,v 1.2 1999/12/10 23:29:48 mdw Exp $ + * $Id$ * * Simple key management * - * (c) 1999 Mark Wooding + * (c) 1999 Straylight/Edgeware */ -/*----- Licensing notice --------------------------------------------------* +/*----- Licensing notice --------------------------------------------------* * * This file is part of Catacomb. * @@ -15,29 +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.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 @@ -51,9 +40,26 @@ #include #include +#include #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 + /*----- Data structures ---------------------------------------------------*/ /* --- Key attributes --- * @@ -76,42 +82,52 @@ typedef struct key_attr { */ typedef struct key { + + /* --- Hashtable management --- */ + hash_base _b; /* Symbol table data */ struct key *next; /* Next key of the same type */ + + /* --- Basic key attributes --- */ + uint32 id; /* Key id used to name it */ + char *tag; /* Textual tag name */ char *type; /* Textual key type */ - void *k; /* Actual key data */ - size_t ksz; /* Size of the key data */ time_t exp, del; /* Expiry times for keys */ + + /* --- The key data itself --- */ + + key_data *k; /* The actual key data */ + + /* --- Other attributes and commentary --- */ + sym_table a; /* Hashtable of key attributes */ char *c; /* Any additional comments */ } key; /* --- The keys-by-type entries --- */ -typedef struct key_type { +typedef struct key_ref { sym_base _b; /* Symbol table data */ key *k; /* Pointer to first key in list */ -} key_type; +} key_ref; /* --- A key file --- */ typedef struct key_file { FILE *fp; /* File pointer open on file */ - int fd; /* File descriptor open on file */ char *name; /* Filename used to create it */ unsigned f; /* Various useful flags */ hash_table byid; /* Table of keys by keyid */ sym_table bytype; /* Table of keys by type */ + sym_table bytag; /* Table of keys by tag */ size_t idload; /* Loading on id table */ } 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 --- * * @@ -122,20 +138,28 @@ 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_UNUSED ((time_t)0) /* Key has never been used */ #define KEXP_FOREVER ((time_t)-1) /* Never expire this key */ #define KEXP_EXPIRE ((time_t)-2) /* Expire this key when unused */ -/* --- Write attempt codes --- */ +/* --- Write error codes --- */ enum { KWRITE_OK, /* Everything went fine */ @@ -143,113 +167,335 @@ enum { KWRITE_BROKEN = -2 /* Key ring needs manual fixing */ }; +/* --- Error reporting functions for @key_merge@ and @key_open@ --- */ + +typedef void key_reporter(const char */*file*/, int /*line*/, + const char */*err*/, void */*p*/); + /* --- Macros for testing expiry --- */ #define KEY_EXPIRED(now, exp) \ ((exp) == KEXP_EXPIRE || ((exp) != KEXP_FOREVER && (exp) < (now))) -#define KEY_DELETED(now, del) ((del) == KEXP_FOREVER || (del) < (now)) +/*----- Reading and writing keys and files --------------------------------*/ + +/* --- @key_merge@ --- * + * + * Arguments: @key_file *f@ = pointer to file structure + * @const char *file@ = name of file (for error messages) + * @FILE *fp@ = file handle to read from + * @key_reporter *rep@ = error reporting function + * @void *arg@ = argument for function + * + * Returns: Error code (one of the @KERR@ constants). + * + * Use: Reads keys from a file, and inserts them into the file. + */ -/*----- Functions provided ------------------------------------------------*/ +extern int key_merge(key_file */*f*/, const char */*file*/, FILE */*fp*/, + key_reporter */*rep*/, void */*arg*/); -/* --- @key_chktype@ --- * +/* --- @key_extract@ --- * * - * Arguments: @const char *type@ = pointer to a type string + * Arguments: @key_file *f@ = pointer to file structure + * @key *k@ = key to extract + * @FILE *fp@ = file to write on + * @const key_filter *kf@ = pointer to key selection block * - * Returns: Zero if OK, -1 on error. + * Returns: Zero if OK, EOF on error. * - * Use: Checks whether a type string is OK. + * Use: Extracts a key to an ouptut file. */ -extern int key_chktype(const char */*type*/); +extern int key_extract(key_file */*f*/, key */*k*/, FILE */*fp*/, + const key_filter */*kf*/); -/* --- @key_chkcomment@ --- * +/* --- @key_open@ --- * * - * Arguments: @const char *comment@ = pointer to a comment string + * Arguments: @key_file *f@ = pointer to file structure to initialize + * @const char *file@ = pointer to the file name + * @unsigned how@ = opening options (@KOPEN_*@). + * @key_reporter *rep@ = error reporting function + * @void *arg@ = argument for function * - * Returns: Zero if OK, -1 on error. + * Returns: Zero if it worked, nonzero otherwise. * - * Use: Checks whether a comment string is OK. + * Use: Opens a key file, reads its contents, and stores them in a + * structure. The file is locked appropriately until closed + * using @key_close@. On an error, everything is cleared away + * tidily. If the file is opened with @KOPEN_WRITE@, it's + * created if necessary, with read and write permissions for its + * owner only. */ -extern int key_chkcomment(const char */*c*/); +extern int key_open(key_file */*f*/, const char */*file*/, unsigned /*how*/, + key_reporter */*rep*/, void */*arg*/); -/* --- @key_mkiter@ --- * +/* --- @key_discard@ --- * * - * Arguments: @key_iter *i@ = pointer to iterator object - * @key_file *f@ = pointer to file structure + * Arguments: @key_file *f@ = pointer to key file block * * Returns: --- * - * Use: Initializes a key iterator. The keys are returned by - * @key_next@. + * Use: Frees all the key data, without writing changes. */ -extern void key_mkiter(key_iter */*i*/, key_file */*f*/); +extern void key_discard(key_file */*f*/); -/* --- @key_next@ --- * +/* --- @key_close@ --- * * - * Arguments: @key_iter *i@ = pointer to iterator object + * Arguments: @key_file *f@ = pointer to key file block * - * Returns: Pointer to next key, or null. + * Returns: A @KWRITE_@ code indicating how it went. * - * Use: Returns the next key in some arbitrary sequence. + * Use: Frees all the key data, writes any changes. Make sure that + * all hell breaks loose if this returns @KWRITE_BROKEN@. */ -extern key *key_next(key_iter */*i*/); +extern int key_close(key_file */*f*/); -/* --- @key_mkattriter@ --- * +/* --- @key_save@ --- * * - * Arguments: @key_attriter *i@ = pointer to attribute iterator - * @key_file *f@ = pointer to key file - * @key *k@ = pointer to key + * Arguments: @key_file *f@ = pointer to key file block * - * Returns: --- + * Returns: A @KWRITE_@ code indicating how well it worked. * - * Use: Initializes an attribute iterator. The attributes are - * returned by @key_nextattr@. + * Use: Writes a key file's data back to the actual file. This code + * is extremely careful about error handling. It should usually + * be able to back out somewhere sensible, but it can tell when + * it's got itself into a real pickle and starts leaving well + * alone. + * + * Callers, please make sure that you ring alarm bells when this + * function returns @KWRITE_BROKEN@. */ -extern void key_mkattriter(key_attriter */*i*/, key_file */*f*/, key */*k*/); +extern int key_save(key_file */*f*/); -/* --- @key_nextattr@ --- * +/* --- @key_lockfile@ --- * * - * Arguments: @key_attriter *i@ = pointer to attribute iterator - * @const char **n, **v@ = pointers to name and value + * Arguments: @key_file *f@ = pointer to file structure to initialize + * @const char *file@ = pointer to the file name + * @unsigned how@ = opening options (@KOPEN_*@). * - * Returns: Zero if no attribute available, or nonzero if returned OK. + * Returns: Zero if it worked, nonzero otherwise. * - * Use: Returns the next attribute. + * Use: Opens a keyfile and stores the information needed for + * continued access in the structure. + * + * If the file is opened with @KOPEN_WRITE@, it's created if + * necessary with read and write permissions for owner only, and + * locked for update while it's open. + * + * This is a system-dependent routine, and only really intended + * for the private use of @key_open@. */ -extern int key_nextattr(key_attriter */*i*/, - const char **/*n*/, const char **/*v*/); +extern int key_lockfile(key_file */*f*/, const char */*file*/, + unsigned /*how*/); -/* --- @key_bytype@ --- * +/*----- Creating and manipulating keys ------------------------------------*/ + +/* --- @key_new@ --- * - * Arguments: @key_file *f@ = key file we want a key from - * @const char *type@ = type string for desired key + * Arguments: @key_file *f@ = pointer to key file + * @uint32 id@ = keyid to set + * @const char *type@ = the type of this key + * @time_t exp@ = when the key expires + * @key *kk@ = where to put the key pointer * - * Returns: Pointer to the best key to use, or null. + * Returns: Error code (one of the @KERR@ constants). * - * Use: Looks up a key by its type. Returns the key with the latest - * expiry time. This function will not return an expired key. + * Use: Attaches a new key to a key file. You must have a writable + * key file for this to work. + * + * The type is a key type string. This interface doesn't care + * about how type strings are formatted: it just treats them as + * opaque gobs of text. Clients are advised to choose some + * standard for representing key types, though. + * + * The expiry time should either be a time in the future, or the + * magic value @KEXP_FOREVER@ which means `never expire this + * key'. Be careful with `forever' keys. If I were you, I'd + * use a more sophisticated key management system than this for + * them. + * + * You have to set the actual key yourself. */ -extern key *key_bytype(key_file */*f*/, const char */*type*/); +extern int key_new(key_file */*f*/, uint32 /*id*/, const char */*type*/, + time_t /*exp*/, key **/*kk*/); -/* --- @key_byid@ --- * +/* --- @key_delete@ --- * * - * Arguments: @key_file *f@ = key file to find a key from - * @uint32 id@ = id to look for + * Arguments: @key_file *f@ = pointer to file block + * @key *k@ = key to delete * - * Returns: Key with matching id. + * Returns: Error code (one of the @KERR@ constants). * - * Use: Returns a key given its id. This function will return an - * expired key, but not a deleted one. + * Use: Removes the given key from the list. The key file must be + * writable. (Due to the horridness of the data structures, + * deleted keys aren't actually removed, just marked so that + * they can't be looked up or iterated over. One upshot of + * this is that they don't get written back to the file when + * it's closed.) */ -extern key *key_byid(key_file */*f*/, uint32 /*id*/); +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 + * @key *k@ = pointer to key block + * + * Returns: Error code (one of the @KERR@ constants). + * + * Use: Immediately marks the key as expired. It may be removed + * immediately, if it is no longer required, and will be removed + * by a tidy operation when it is no longer required. The key + * file must be writable. + */ + +extern int key_expire(key_file */*f*/, key */*k*/); + +/* --- @key_used@ --- * + * + * Arguments: @key_file *f@ = pointer to key file + * @key *k@ = pointer to key block + * @time_t t@ = when key can be removed + * + * Returns: Zero if OK, nonzero on failure. + * + * Use: Marks a key as being required until a given time. Even + * though the key may expire before then (and won't be returned + * by type after that time), it will still be available when + * requested explicitly by id. The key file must be writable. + * + * The only (current) reason for failure is attempting to use + * a key which can expire for something which can't. + */ + +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@ --- * + * + * Arguments: @const char *p@ = pointer to a type string + * + * Returns: Zero if OK, -1 on error. + * + * Use: Checks whether an identification component string is OK. + */ + +extern int key_chkident(const char */*p*/); + +/* --- @key_chkcomment@ --- * + * + * Arguments: @const char *p@ = pointer to a comment string + * + * Returns: Zero if OK, -1 on error. + * + * Use: Checks whether a comment string is OK. + */ + +extern int key_chkcomment(const char */*p*/); + +/* --- @key_setcomment@ --- * + * + * Arguments: @key_file *f@ = pointer to key file block + * @key *k@ = pointer to key block + * @const char *c@ = pointer to comment to set, or zero + * + * Returns: Error code (one of the @KERR@ constants). + * + * Use: Replaces the key's current comment with a new one. + */ + +extern int key_setcomment(key_file */*f*/, key */*k*/, const char */*c*/); + +/* --- @key_settag@ --- * + * + * Arguments: @key_file *f@ = pointer to key file block + * @key *k@ = pointer to key block + * @const char *tag@ = pointer to comment to set, or zero + * + * Returns: Error code (one of the @KERR@ constants). + * + * Use: Replaces the key's current tag with a new one. + */ + +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 + * @dstr *d@ = pointer to destination string + * + * Returns: --- + * + * Use: Emits the key's full tag, which has the form + * `ID:TYPE[:TAG]'. This is used in the textual file format, + * and to identify passphrases for locked keys. + */ + +extern void key_fulltag(key */*k*/, dstr */*d*/); + +/* --- @key_qtag@ --- * + * + * Arguments: @key_file *f@ = key file to find a key from + * @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 + * + * Returns: Zero if OK, nonzero if it failed. + * + * Use: Performs a full lookup on a qualified tag name. The tag is + * 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. + */ + +extern int key_qtag(key_file */*f*/, const char */*tag*/, + dstr */*d*/, key **/*k*/, key_data ***/*kd*/); /* --- @key_getattr@ --- * * @@ -270,191 +516,182 @@ extern const char *key_getattr(key_file */*f*/, key */*k*/, * Arguments: @key_file *f@ = pointer to file * @key *k@ = pointer to key * @const char *n@ = pointer to attribute name - * @const char *v@ = pointer to attribute value + * @const char *v@ = pointer to attribute value or null * - * Returns: --- + * Returns: Error code (one of the @KERR@ constants). * * Use: Inserts an attribute on a key. If an attribute with the same - * name already exists, it is deleted. + * name already exists, it is deleted. Setting a null value + * removes the attribute. */ -extern void key_putattr(key_file */*f*/, key */*k*/, - const char */*n*/, const char */*v*/); +extern int key_putattr(key_file */*f*/, key */*k*/, + const char */*n*/, const char */*v*/); -/* --- @key_setcomment@ --- * +/* --- @key_mkattriter@ --- * * - * Arguments: @key_file *f@ = pointer to key file block - * @key *k@ = pointer to key block - * @const char *c@ = pointer to comment to set, or zero + * Arguments: @key_attriter *i@ = pointer to attribute iterator + * @key *k@ = pointer to key * * Returns: --- * - * Use: Replaces the key's current comment with a new one. + * Use: Initializes an attribute iterator. The attributes are + * returned by @key_nextattr@. */ -extern void key_setcomment(key_file */*f*/, key */*k*/, const char */*c*/); +extern void key_mkattriter(key_attriter */*i*/, key */*k*/); -/* --- @key_merge@ --- * +/* --- @key_nextattr@ --- * * - * Arguments: @key_file *f@ = pointer to file structure - * @const char *file@ = name of file (for error messages) - * @FILE *fp@ = file handle to read from + * Arguments: @key_attriter *i@ = pointer to attribute iterator + * @const char **n, **v@ = pointers to name and value * - * Returns: --- + * Returns: Zero if no attribute available, or nonzero if returned OK. * - * Use: Reads keys from a file, and inserts them into the file. + * Use: Returns the next attribute. */ -extern void key_merge(key_file */*f*/, const char */*file*/, FILE */*fp*/); +extern int key_nextattr(key_attriter */*i*/, + const char **/*n*/, const char **/*v*/); + +/*----- Searching and iterating -------------------------------------------*/ -/* --- @key_extract@ --- * +/* --- @key_bytype@ --- * * - * Arguments: @key_file *f@ = pointer to file structure - * @key *k@ = key to extract - * @FILE *fp@ = file to write on + * Arguments: @key_file *f@ = key file we want a key from + * @const char *type@ = type string for desired key * - * Returns: Zero if OK, EOF on error. + * Returns: Pointer to the best key to use, or null. * - * Use: Extracts a key to an ouptut file. + * Use: Looks up a key by its type. Returns the key with the latest + * expiry time. This function will not return an expired key. */ -extern int key_extract(key_file */*f*/, key */*k*/, FILE */*fp*/); +extern key *key_bytype(key_file */*f*/, const char */*type*/); -/* --- @key_write@ --- * - * - * Arguments: @key_file *f@ = pointer to key file block +/* --- @key_byid@ --- * * - * Returns: A @KWRITE_@ code indicating how well it worked. + * Arguments: @key_file *f@ = key file to find a key from + * @uint32 id@ = id to look for * - * Use: Writes a key file's data back to the actual file. This code - * is extremely careful about error handling. It should usually - * be able to back out somewhere sensible, but it can tell when - * it's got itself into a real pickle and starts leaving well - * alone. + * Returns: Key with matching id. * - * Callers, please make sure that you ring alarm bells when this - * function returns @KWRITE_BROKEN@. + * Use: Returns a key given its id. This function will return an + * expired key, but not a deleted one. */ -extern int key_write(key_file */*f*/); +extern key *key_byid(key_file */*f*/, uint32 /*id*/); -/* --- @key_open@ --- * +/* --- @key_bytag@ --- * * - * Arguments: @key_file *f@ = pointer to file structure to initialize - * @const char *file@ = pointer to the file name - * @int how@ = opening options (@KOPEN_*@). + * Arguments: @key_file *f@ = key file to find a key from + * @const char *tag@ = pointer to tag string * - * Returns: Zero if it worked, nonzero otherwise. + * Returns: Key with matching id or tag. * - * Use: Opens a key file, reads its contents, and stores them in a - * structure. The file is locked appropriately until closed - * using @key_close@. On an error, everything is cleared away - * tidily. If the file is opened with @KOPEN_WRITE@, it's - * created if necessary, with read and write permissions for its - * owner only. + * Use: Returns a key given its tag or id. This function will return + * an expired key, but not a deleted one. */ -extern int key_open(key_file */*f*/, const char */*file*/, int /*how*/); +extern key *key_bytag(key_file */*f*/, const char */*tag*/); -/* --- @key_close@ --- * +/* --- @key_mkiter@ --- * * - * Arguments: @key_file *f@ = pointer to key file block + * Arguments: @key_iter *i@ = pointer to iterator object + * @key_file *f@ = pointer to file structure * - * Returns: A @KWRITE_@ code indicating how it went. + * Returns: --- * - * Use: Frees all the key data, writes any changes. Make sure that - * all hell breaks loose if this returns @KWRITE_BROKEN@. + * Use: Initializes a key iterator. The keys are returned by + * @key_next@. */ -extern int key_close(key_file */*f*/); +extern void key_mkiter(key_iter */*i*/, key_file */*f*/); -/* --- @key_new@ --- +/* --- @key_next@ --- * * - * Arguments: @key_file *f@ = pointer to key file - * @const char *type@ = the type of this key - * @const void *k@ = pointer to key data - * @size_t ksz@ = size of key data - * @time_t exp@ = when the key expires - * @const char *c@ = textual comment to attach + * Arguments: @key_iter *i@ = pointer to iterator object * - * Returns: Key block containing new data, or null if it couldn't be - * done. + * Returns: Pointer to next key, or null. * - * Use: Attaches a new key to a key file. You must have a writable - * key file for this to work. + * Use: Returns the next key in some arbitrary sequence. + */ + +extern key *key_next(key_iter */*i*/); + +/*----- Fetching key data conveniently ------------------------------------*/ + +/* --- @key_fetchinit@ --- * * - * The type is a key type string. This interface doesn't care - * about how type strings are formatted: it just treats them as - * opaque gobs of text. Clients are advised to choose some - * standard for representing key types, though. + * Arguments: @const key_fetchdef *kf@ = pointer to base definition + * @key_packstruct *kps@ = pointer to destination packing def + * @void *p@ = pointer to destination block * - * The key can be any old binary mess. + * Returns: Pointer to packing definition. * - * The expiry time should either be a time in the future, or the - * magic value @KEXP_FOREVER@ which means `never expire this - * key'. Be careful with `forever' keys. If I were you, I'd - * use a more sophisticated key management system than this for - * them. + * 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 * - * The comment can be any old text not containing newlines or - * nulls. This interface doesn't impose any length restrictions - * on comment lengths. + * Returns: Error code, or zero. + * + * Use: Fetches an unpacked key from a packed one. */ -extern key *key_new(key_file */*f*/, const char */*type*/, - const void */*k*/, size_t /*ksz*/, - time_t /*exp*/, const char */*c*/); +extern int key_fetch(key_packdef */*kp*/, key */*k*/); -/* --- @key_delete@ --- * +/* --- @key_fetchbyname@ --- * * - * Arguments: @key_file *f@ = pointer to file block - * @key *k@ = key to delete + * 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: --- + * Returns: Error code, or zero. * - * Use: Removes the given key from the list. The key file must be - * writable. (Due to the horridness of the data structures, - * deleted keys aren't actually removed, just marked so that - * they can't be looked up or iterated over. One upshot of - * this is that they don't get written back to the file when - * it's closed.) + * Use: Fetches a named key from a key file and unpacks it + * conveniently. */ -extern void key_delete(key_file */*f*/, key */*k*/); +extern int key_fetchbyname(key_packdef */*kp*/, + key_file */*kf*/, const char */*tag*/); -/* --- @key_expire@ --- * +/* --- @key_fetchdone@ --- * * - * Arguments: @key_file *f@ = pointer to file block - * @key *k@ = pointer to key block + * Arguments: @key_packdef *kp@ = pointer to packing structure * * Returns: --- * - * Use: Immediately marks the key as expired. It may be removed - * immediately, if it is no longer required, and will be removed - * by a tidy operation when it is no longer required. The key - * file must be writable. + * Use: Frees a packing structure. If the structure was allocated by + * @key_fetchinit@ then it is freed. */ -extern void key_expire(key_file */*f*/, key */*k*/); +extern void key_fetchdone(key_packdef */*kp*/); -/* --- @key_used@ --- * - * - * Arguments: @key_file *f@ = pointer to key file - * @key *k@ = pointer to key block - * @time_t t@ = when key can be removed +/*----- Other functions ---------------------------------------------------*/ + +/* --- @key_moan@ --- * * - * Returns: Zero if OK, nonzero on failure. + * Arguments: @const char *file@ = name of the file + * @int line@ = line number in file + * @const char *msg@ = error message + * @void *p@ = argument pointer * - * Use: Marks a key as being required until a given time. Even - * though the key may expire before then (and won't be returned - * by type after that time), it will still be available when - * requested explicitly by id. The key file must be writable. + * Returns: --- * - * The only (current) reason for failure is attempting to use - * a key which can expire for something which can't. + * Use: Reports an error message about loading a key file. */ -extern int key_used(key_file */*f*/, key */*k*/, time_t /*t*/); +extern void key_moan(const char */*file*/, int /*line*/, + const char */*msg*/, void */*p*/); /*----- That's all, folks -------------------------------------------------*/