/* -*-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.
*
* 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
#include <mLib/hash.h>
#include <mLib/sym.h>
+#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
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
typedef struct key {
/* --- Hashtable management --- */
-
+
hash_base _b; /* Symbol table data */
struct key *next; /* Next key of the same type */
/* --- The key data itself --- */
- key_data k; /* The actual key data */
+ key_data *k; /* The actual key data */
/* --- Other attributes and commentary --- */
/* --- 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 --- *
*
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 {
#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@ --- *
*
* 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
*
* 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
*
* 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.
*
* 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 ------------------------------------*/
* @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.
* 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@ --- *
*
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
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@ --- *
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
* @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.
*
* 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@ --- *
*
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@ --- *
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
projects / u / mdw / catacomb / blobdiff