/* -*-c-*-
*
- * $Id: key.h,v 1.5 2000/02/12 18:55:40 mdw Exp $
+ * $Id$
*
* Simple key management
*
* MA 02111-1307, USA.
*/
-/*----- Revision history --------------------------------------------------*
- *
- * $Log: key.h,v $
- * Revision 1.5 2000/02/12 18:55:40 mdw
- * Make it all compile properly.
- *
- * Revision 1.4 2000/02/12 18:21:02 mdw
- * Overhaul of key management (again).
- *
- * 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
/* --- 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 = 0, /* 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_BADPASS = -10, /* Error decrypting locked key */
- KERR_WRONGTYPE = -11, /* Key has incorrect type */
- KERR_NOTFOUND = -12, /* Key couldn't be found */
- KERR_MAX /* Largest possible error */
-};
-
/* --- Write error codes --- */
enum {
*
* 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 ------------------------------------*/
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 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