X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/6f51228e8b99c2f0cbec5cb9d77925e0031eacd8..d11a0bf77a5230387d222ec727865a898767ff3e:/key.h diff --git a/key.h b/key.h index 3874f2c..6a17ded 100644 --- a/key.h +++ b/key.h @@ -1,10 +1,10 @@ /* -*-c-*- * - * $Id: key.h,v 1.2 1999/12/10 23:29:48 mdw Exp $ + * $Id: key.h,v 1.3 1999/12/22 15:47:48 mdw Exp $ * * Simple key management * - * (c) 1999 Mark Wooding + * (c) 1999 Straylight/Edgeware */ /*----- Licensing notice --------------------------------------------------* @@ -30,6 +30,9 @@ /*----- 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. * @@ -51,9 +54,14 @@ #include #include +#include #include #include +#ifndef CATACOMB_MP_H +# include "mp.h" +#endif + /*----- Data structures ---------------------------------------------------*/ /* --- Key attributes --- * @@ -68,6 +76,99 @@ 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 @@ -76,33 +177,45 @@ 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; @@ -131,11 +244,26 @@ enum { /* --- 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 --- */ +/* --- 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 { KWRITE_OK, /* Everything went fine */ @@ -143,206 +271,294 @@ 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)) +/*----- Key data manipulation ---------------------------------------------*/ + +/* --- @key_destroy@ --- * + * + * Arguments: @key_data *k@ = pointer to key data to destroy + * + * Returns: --- + * + * Use: Destroys a lump of key data. + */ -/*----- Functions provided ------------------------------------------------*/ +extern void key_destroy(key_data */*k*/); -/* --- @key_chktype@ --- * +/* --- @key_readflags@ --- * * - * Arguments: @const char *type@ = pointer to a type string + * 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 OK, -1 on error. + * Returns: Zero if all went well, nonzero if there was an error. * - * Use: Checks whether a type string is OK. + * Use: Reads a flag string. */ -extern int key_chktype(const char */*type*/); +extern int key_readflags(const char */*p*/, char **/*pp*/, + unsigned */*ff*/, unsigned */*mm*/); -/* --- @key_chkcomment@ --- * +/* --- @key_writeflags@ --- * * - * Arguments: @const char *comment@ = pointer to a comment string + * Arguments: @unsigned f@ = flags to write + * @dstr *d@ = pointer to destination string * - * Returns: Zero if OK, -1 on error. + * Returns: --- * - * Use: Checks whether a comment string is OK. + * Use: Emits a flags word as a string representation. */ -extern int key_chkcomment(const char */*c*/); +extern void key_writeflags(unsigned /*f*/, dstr */*d*/); -/* --- @key_mkiter@ --- * +/* --- @key_binary@ --- * * - * Arguments: @key_iter *i@ = pointer to iterator object - * @key_file *f@ = pointer to file structure + * 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: Initializes a key iterator. The keys are returned by - * @key_next@. + * Use: Sets a binary key in a key data block. */ -extern void key_mkiter(key_iter */*i*/, key_file */*f*/); +extern void key_binary(key_data */*k*/, const void */*p*/, size_t /*sz*/); -/* --- @key_next@ --- * +/* --- @key_encrypted@ --- * * - * Arguments: @key_iter *i@ = pointer to iterator object + * 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: Pointer to next key, or null. + * Returns: --- * - * Use: Returns the next key in some arbitrary sequence. + * Use: Sets an encrypted key in a key data block. */ -extern key *key_next(key_iter */*i*/); +extern void key_encrypted(key_data */*k*/, const void */*p*/, size_t /*sz*/); -/* --- @key_mkattriter@ --- * +/* --- @key_mp@ --- * * - * Arguments: @key_attriter *i@ = pointer to attribute iterator - * @key_file *f@ = pointer to key file - * @key *k@ = pointer to key + * Arguments: @key_data *k@ = pointer to key data block + * @mp *m@ = pointer to the value to set * * Returns: --- * - * Use: Initializes an attribute iterator. The attributes are - * returned by @key_nextattr@. + * Use: Sets a multiprecision integer key in a key block. */ -extern void key_mkattriter(key_attriter */*i*/, key_file */*f*/, key */*k*/); +extern void key_mp(key_data */*k*/, mp */*m*/); -/* --- @key_nextattr@ --- * +/* --- @key_structure@ --- * * - * Arguments: @key_attriter *i@ = pointer to attribute iterator - * @const char **n, **v@ = pointers to name and value + * Arguments: @key_data *k@ = pointer to key data block * - * Returns: Zero if no attribute available, or nonzero if returned OK. + * Returns: --- * - * Use: Returns the next attribute. + * Use: Initializes a structured key type. */ -extern int key_nextattr(key_attriter */*i*/, - const char **/*n*/, const char **/*v*/); +extern void key_structure(key_data */*k*/); -/* --- @key_bytype@ --- * +/* --- @key_structfind@ --- * * - * Arguments: @key_file *f@ = key file we want a key from - * @const char *type@ = type string for desired key + * Arguments: @key_data *k@ = pointer to key data block + * @const char *tag@ = pointer to tag string * - * Returns: Pointer to the best key to use, or null. + * Returns: Pointer to key data block, or null. * - * 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: Looks up the tag in a structured key. */ -extern key *key_bytype(key_file */*f*/, const char */*type*/); +extern key_data *key_structfind(key_data */*k*/, const char */*tag*/); -/* --- @key_byid@ --- * +/* --- @key_structcreate@ --- * * - * Arguments: @key_file *f@ = key file to find a key from - * @uint32 id@ = id to look for + * Arguments: @key_data *k@ = pointer to key data block + * @const char *tag@ = pointer to tag string * - * Returns: Key with matching id. + * Returns: Pointer to newly created key data. * - * Use: Returns a key given its id. This function will return an - * expired key, but not a deleted one. + * Use: Creates a new uninitialized subkey. */ -extern key *key_byid(key_file */*f*/, uint32 /*id*/); +extern key_data *key_structcreate(key_data */*k*/, const char */*tag*/); -/* --- @key_getattr@ --- * +/* --- @key_match@ --- * * - * Arguments: @key_file *f@ = pointer to file - * @key *k@ = pointer to key - * @const char *n@ = pointer to attribute name + * Arguments: @key_data *k@ = pointer to key data block + * @const key_filter *kf@ = pointer to filter block * - * Returns: Pointer to attribute value, or null if not found. + * Returns: Nonzero if the key matches the filter. * - * Use: Returns the value of a key attribute. + * Use: Checks whether a key matches a filter. */ -extern const char *key_getattr(key_file */*f*/, key */*k*/, - const char */*n*/); +extern int key_match(key_data */*k*/, const key_filter */*kf*/); -/* --- @key_putattr@ --- * +/* --- @key_do@ --- * * - * 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 + * 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: --- + * Returns: Nonzero return code from function, or zero. * - * Use: Inserts an attribute on a key. If an attribute with the same - * name already exists, it is deleted. + * Use: Runs a function over all the leaves of a key. */ -extern void key_putattr(key_file */*f*/, key */*k*/, - const char */*n*/, const char */*v*/); +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_setcomment@ --- * +/* --- @key_copy@ --- * * - * 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_data *kd@ = pointer to destination data block + * @key_data *k@ = pointer to source data block + * @const key_filter *kf@ = pointer to filter block * - * Returns: --- + * Returns: Nonzero if an item was actually copied. * - * Use: Replaces the key's current comment with a new one. + * 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 void key_setcomment(key_file */*f*/, key */*k*/, const char */*c*/); +extern int key_punlock(const char */*tag*/, + key_data */*k*/, key_data */*kt*/); + +/*----- 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: --- + * Returns: Error code (one of the @KERR@ constants). * * Use: Reads keys from a file, and inserts them into the file. */ -extern void key_merge(key_file */*f*/, const char */*file*/, FILE */*fp*/); +extern int key_merge(key_file */*f*/, const char */*file*/, FILE */*fp*/, + key_reporter */*rep*/, void */*arg*/); /* --- @key_extract@ --- * * * 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, EOF on error. * * Use: Extracts a key to an ouptut file. */ -extern int key_extract(key_file */*f*/, key */*k*/, FILE */*fp*/); - -/* --- @key_write@ --- * - * - * Arguments: @key_file *f@ = pointer to key file block - * - * Returns: A @KWRITE_@ code indicating how well it worked. - * - * 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 int key_write(key_file */*f*/); +extern int key_extract(key_file */*f*/, key */*k*/, FILE */*fp*/, + const key_filter */*kf*/); /* --- @key_open@ --- * * * Arguments: @key_file *f@ = pointer to file structure to initialize * @const char *file@ = pointer to the file name * @int how@ = opening options (@KOPEN_*@). + * @key_reporter *rep@ = error reporting function + * @void *arg@ = argument for function * * Returns: Zero if it worked, nonzero otherwise. * @@ -354,7 +570,8 @@ extern int key_write(key_file */*f*/); * owner only. */ -extern int key_open(key_file */*f*/, const char */*file*/, int /*how*/); +extern int key_open(key_file */*f*/, const char */*file*/, int /*how*/, + key_reporter */*rep*/, void */*arg*/); /* --- @key_close@ --- * * @@ -368,14 +585,54 @@ extern int key_open(key_file */*f*/, const char */*file*/, int /*how*/); extern int key_close(key_file */*f*/); +/* --- @key_save@ --- * + * + * Arguments: @key_file *f@ = pointer to key file block + * + * Returns: A @KWRITE_@ code indicating how well it worked. + * + * 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 int key_save(key_file */*f*/); + +/* --- @key_lockfile@ --- * + * + * Arguments: @key_file *f@ = pointer to file structure to initialize + * @const char *file@ = pointer to the file name + * @int how@ = opening options (@KOPEN_*@). + * + * Returns: Zero if it worked, nonzero otherwise. + * + * 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_lockfile(key_file */*f*/, const char */*file*/, int /*how*/); + +/*----- Creating and manipulating keys ------------------------------------*/ + /* --- @key_new@ --- * * Arguments: @key_file *f@ = pointer to key file + * @uint32 id@ = keyid to set * @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 + * @int *err@ = where to store the error condition * * Returns: Key block containing new data, or null if it couldn't be * done. @@ -388,29 +645,24 @@ extern int key_close(key_file */*f*/); * opaque gobs of text. Clients are advised to choose some * standard for representing key types, though. * - * The key can be any old binary mess. - * * 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. * - * The comment can be any old text not containing newlines or - * nulls. This interface doesn't impose any length restrictions - * on comment lengths. + * You have to set the actual key yourself. */ -extern key *key_new(key_file */*f*/, const char */*type*/, - const void */*k*/, size_t /*ksz*/, - time_t /*exp*/, const char */*c*/); +extern key *key_new(key_file */*f*/, uint32 /*id*/, const char */*type*/, + time_t /*exp*/, int */*err*/); /* --- @key_delete@ --- * * * Arguments: @key_file *f@ = pointer to file block * @key *k@ = key to delete * - * Returns: --- + * Returns: Error code (one of the @KERR@ constants). * * Use: Removes the given key from the list. The key file must be * writable. (Due to the horridness of the data structures, @@ -420,14 +672,14 @@ extern key *key_new(key_file */*f*/, const char */*type*/, * it's closed.) */ -extern void key_delete(key_file */*f*/, key */*k*/); +extern int key_delete(key_file */*f*/, key */*k*/); /* --- @key_expire@ --- * * * Arguments: @key_file *f@ = pointer to file block * @key *k@ = pointer to key block * - * Returns: --- + * 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 @@ -435,7 +687,7 @@ extern void key_delete(key_file */*f*/, key */*k*/); * file must be writable. */ -extern void key_expire(key_file */*f*/, key */*k*/); +extern int key_expire(key_file */*f*/, key */*k*/); /* --- @key_used@ --- * * @@ -456,6 +708,240 @@ extern void key_expire(key_file */*f*/, key */*k*/); extern int key_used(key_file */*f*/, key */*k*/, time_t /*t*/); +/*----- 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_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@ --- * + * + * Arguments: @key_file *f@ = pointer to file + * @key *k@ = pointer to key + * @const char *n@ = pointer to attribute name + * + * Returns: Pointer to attribute value, or null if not found. + * + * Use: Returns the value of a key attribute. + */ + +extern const char *key_getattr(key_file */*f*/, key */*k*/, + const char */*n*/); + +/* --- @key_putattr@ --- * + * + * 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 or null + * + * 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. Setting a null value + * removes the attribute. + */ + +extern int key_putattr(key_file */*f*/, key */*k*/, + const char */*n*/, const char */*v*/); + +/* --- @key_mkattriter@ --- * + * + * Arguments: @key_attriter *i@ = pointer to attribute iterator + * @key *k@ = pointer to key + * + * Returns: --- + * + * Use: Initializes an attribute iterator. The attributes are + * returned by @key_nextattr@. + */ + +extern void key_mkattriter(key_attriter */*i*/, key */*k*/); + +/* --- @key_nextattr@ --- * + * + * Arguments: @key_attriter *i@ = pointer to attribute iterator + * @const char **n, **v@ = pointers to name and value + * + * Returns: Zero if no attribute available, or nonzero if returned OK. + * + * Use: Returns the next attribute. + */ + +extern int key_nextattr(key_attriter */*i*/, + const char **/*n*/, const char **/*v*/); + +/*----- Searching and iterating -------------------------------------------*/ + +/* --- @key_bytype@ --- * + * + * Arguments: @key_file *f@ = key file we want a key from + * @const char *type@ = type string for desired key + * + * Returns: Pointer to the best key to use, or null. + * + * 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 key *key_bytype(key_file */*f*/, const char */*type*/); + +/* --- @key_byid@ --- * + * + * Arguments: @key_file *f@ = key file to find a key from + * @uint32 id@ = id to look for + * + * Returns: Key with matching id. + * + * Use: Returns a key given its id. This function will return an + * expired key, but not a deleted one. + */ + +extern key *key_byid(key_file */*f*/, uint32 /*id*/); + +/* --- @key_bytag@ --- * + * + * Arguments: @key_file *f@ = key file to find a key from + * @const char *tag@ = pointer to tag string + * + * Returns: Key with matching id or tag. + * + * Use: Returns a key given its tag or id. This function will return + * an expired key, but not a deleted one. + */ + +extern key *key_bytag(key_file */*f*/, const char */*tag*/); + +/* --- @key_mkiter@ --- * + * + * Arguments: @key_iter *i@ = pointer to iterator object + * @key_file *f@ = pointer to file structure + * + * Returns: --- + * + * Use: Initializes a key iterator. The keys are returned by + * @key_next@. + */ + +extern void key_mkiter(key_iter */*i*/, key_file */*f*/); + +/* --- @key_next@ --- * + * + * Arguments: @key_iter *i@ = pointer to iterator object + * + * Returns: Pointer to next key, or null. + * + * Use: Returns the next key in some arbitrary sequence. + */ + +extern key *key_next(key_iter */*i*/); + +/*----- Other functions ---------------------------------------------------*/ + +/* --- @key_moan@ --- * + * + * Arguments: @const char *file@ = name of the file + * @int line@ = line number in file + * @const char *msg@ = error message + * @void *p@ = argument pointer + * + * Returns: --- + * + * Use: Reports an error message about loading a key file. + */ + +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