typedef struct key_data {
unsigned e; /* Encoding type for key data */
+ unsigned ref; /* Reference counter */
union {
key_bin k; /* Binary key data */
mp *m; /* Multiprecision integer */
typedef struct key_struct {
sym_base _b;
- key_data k;
+ key_data *k;
} key_struct;
+typedef struct key_subkeyiter { sym_iter i; } key_subkeyiter;
+
/* --- Packing and unpacking --- */
typedef struct key_packdef {
+ unsigned e; /* Key data encoding type */
void *p; /* Pointer to the destination */
- key_data kd; /* Key data block */
+ key_data *kd; /* Key data block */
} key_packdef;
typedef struct key_packstruct {
/* --- Other flags --- */
KF_BURN = 0x10, /* Burn key after use */
- KF_TEMP = 0x20, /* Temporary copy flag */
- KF_OPT = 0x40, /* Optional key (for @key_unpack@) */
+ KF_OPT = 0x20, /* Optional key (for @key_unpack@) */
/* --- Tag end --- */
/*----- Setting new key data ----------------------------------------------*/
-/* --- @key_binary@ --- *
+/* --- @key_newraw@ --- *
*
- * Arguments: @key_data *k@ = pointer to key data block
+ * Arguments: @unsigned e@ = encoding type to set
+ *
+ * Returns: New key block, not filled in.
+ */
+
+extern key_data *key_newraw(unsigned /*e*/);
+
+/* --- @key_newbinary@ --- *
+ *
+ * Arguments: @unsigned e@ = other encoding flags
* @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.
+ * Returns: New key data object.
*/
-extern void key_binary(key_data */*k*/, const void */*p*/, size_t /*sz*/);
+extern key_data *key_newbinary(unsigned /*e*/,
+ const void */*p*/, size_t /*sz*/);
-/* --- @key_encrypted@ --- *
+/* --- @key_newencrypted@ --- *
*
- * Arguments: @key_data *k@ = pointer to key data block
+ * Arguments: @unsigned e@ = other encoding flags
* @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.
+ * Returns: New key data object.
*/
-extern void key_encrypted(key_data */*k*/, const void */*p*/, size_t /*sz*/);
+extern key_data *key_newencrypted(unsigned /*e*/,
+ const void */*p*/, size_t /*sz*/);
-/* --- @key_mp@ --- *
+/* --- @key_mewmp@ --- *
*
- * Arguments: @key_data *k@ = pointer to key data block
+ * Arguments: @unsigned e@ = other encoding flags
* @mp *m@ = pointer to the value to set
*
- * Returns: ---
- *
- * Use: Sets a multiprecision integer key in a key block.
+ * Returns: New key data object.
*/
-extern void key_mp(key_data */*k*/, mp */*m*/);
+extern key_data *key_newmp(unsigned /*e*/, mp */*m*/);
-/* --- @key_string@ --- *
+/* --- @key_newstring@ --- *
*
- * Arguments: @key_data *k@ = pointer to key data block
+ * Arguments: @unsigned e@ = other encoding flags
* @const char *p@ = pointer to the value to set
*
- * Returns: ---
- *
- * Use: Sets a plain string in a key block.
+ * Returns: New key data object.
*/
-extern void key_string(key_data */*k*/, const char */*p*/);
+extern key_data *key_newstring(unsigned /*e*/, const char */*p*/);
-/* --- @key_ec@ --- *
+/* --- @key_newec@ --- *
*
- * Arguments: @key_data *k@ = pointer to key data block
- * @const ec *e@ = pointer to the value to set
+ * Arguments: @unsigned e@ = other encoding flags
+ * @const ec *pt@ = pointer to the value to set
*
- * Returns: ---
- *
- * Use: Sets an elliptic curve point in a key block.
+ * Returns: New key data object.
*/
-extern void key_ec(key_data */*k*/, const ec */*e*/);
+extern key_data *key_newec(unsigned /*e*/, const ec */*pt*/);
-/* --- @key_structure@ --- *
+/* --- @key_newstruct@ --- *
*
- * Arguments: @key_data *k@ = pointer to key data block
+ * Arguments: ---
*
- * Returns: ---
- *
- * Use: Initializes a structured key type.
+ * Returns: New key data object.
*/
-extern void key_structure(key_data */*k*/);
+extern key_data *key_newstruct(void);
/* --- @key_structfind@ --- *
*
extern key_data *key_structfind(key_data */*k*/, const char */*tag*/);
-/* --- @key_structcreate@ --- *
+/* --- @key_mksubkeyiter@ --- *
+ *
+ * Arguments: @key_subkeyiter *i@ = pointer to iterator block
+ * @key_data *k@ = pointer to key data block
+ *
+ * Returns: ---
+ *
+ * Use: Initializes a subkey iterator.
+ */
+
+extern void key_mksubkeyiter(key_subkeyiter */*i*/, key_data */*k*/);
+
+/* --- @key_nextsubkey@ --- *
+ *
+ * Arguments: @key_structiter *i@ = pointer to iterator block
+ * @const char **tag@ = where to put the tag pointer, or null
+ * @key_data **kd@ = where to put the key data pointer, or null
+ *
+ * Returns: Nonzero if there was another item, zero if we hit the
+ * end-stop.
+ *
+ * Use: Collects the next subkey of a structured key.
+ */
+
+extern int key_nextsubkey(key_subkeyiter */*i*/,
+ const char **/*tag*/, key_data **/*kd*/);
+
+/* --- @key_structset@, @key_structsteal@ --- *
*
* Arguments: @key_data *k@ = pointer to key data block
* @const char *tag@ = pointer to tag string
+ * @key_data *kd@ = new key data to store
*
- * Returns: Pointer to newly created key data.
+ * Returns: ---
*
- * Use: Creates a new uninitialized subkey.
+ * Use: Creates a new subkey. Stealing doesn't affect @kd@'s
+ * refcount. If @kd@ is null, the subkey is deleted.
*/
-extern key_data *key_structcreate(key_data */*k*/, const char */*tag*/);
+extern void key_structset(key_data */*k*/,
+ const char */*tag*/, key_data */*kd*/);
+extern void key_structsteal(key_data */*k*/,
+ const char */*tag*/, key_data */*kd*/);
+
+/* --- @key_split@ --- *
+ *
+ * Arguments: @key_data **kk@ = address of pointer to key data block
+ *
+ * Returns: ---
+ *
+ * Use: Replaces @*kk@ with a pointer to the same key data, but with
+ * just one reference.
+ */
+
+extern void key_split(key_data **/*kk*/);
/*----- Miscellaneous operations ------------------------------------------*/
+/* --- @key_incref@ --- *
+ *
+ * Arguments: @key_data *k@ = pointer to key data
+ *
+ * Returns: ---
+ *
+ * Use: Increments the refcount on a key data block.
+ */
+
+#define KEY_INCREF(k) ((k)->ref++)
+extern void key_incref(key_data */*k*/);
+
/* --- @key_destroy@ --- *
*
* Arguments: @key_data *k@ = pointer to key data to destroy
*
* Returns: ---
*
- * Use: Destroys a lump of key data.
+ * Use: Destroys a block of key data, regardless of reference count.
+ * Don't use this unless you know what you're doing.
*/
extern void key_destroy(key_data */*k*/);
+/* --- @key_drop@ --- *
+ *
+ * Arguments: @key_data *k@ = pointer to key data to destroy
+ *
+ * Returns: ---
+ *
+ * Use: Drops a reference to key data, destroying it if necessary.
+ */
+
+#define KEY_DROP(k) do { \
+ key_data *_k = k; \
+ _k->ref--; \
+ if (_k->ref == 0) \
+ key_destroy(_k); \
+} while (0)
+
+extern void key_drop(key_data */*k*/);
+
/* --- @key_do@ --- *
*
* Arguments: @key_data *k@ = pointer to key data block
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*/);
-
/*----- Textual encoding --------------------------------------------------*/
/* --- @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.
+ * Returns: The newly-read key data, or null if it failed.
*
* Use: Parses a textual key description.
*/
-extern int key_read(const char */*p*/, key_data */*k*/, char **/*pp*/);
+extern key_data *key_read(const char */*p*/, char **/*pp*/);
/* --- @key_write@ --- *
*
* Use: Writes a key in a textual encoding.
*/
-extern int key_write(key_data */*k*/, dstr */*d*/,
- const key_filter */*kf*/);
+extern int key_write(key_data */*k*/, dstr */*d*/, const key_filter */*kf*/);
/*----- Key binary encoding -----------------------------------------------*/
*
* 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.
+ * Returns: The newly-read key data, or null if it failed.
*
* Use: Decodes a binary representation of a key.
*/
-extern int key_decode(const void */*p*/, size_t /*sz*/, key_data */*k*/);
+extern key_data *key_decode(const void */*p*/, size_t /*sz*/);
/* --- @key_encode@ --- *
*
/* --- @key_pack@ --- *
*
* Arguments: @key_packdef *kp@ = pointer to packing structure
- * @key_data *kd@ = pointer to destination key data
+ * @key_data **kd@ = where to put the key data pointer
* @dstr *d@ = pointer to tag string for the key data
*
* Returns: Error code, or zero.
* Use: Packs a key from a data structure.
*/
-extern int key_pack(key_packdef */*kp*/, key_data */*kd*/, dstr */*d*/);
+extern int key_pack(key_packdef */*kp*/, key_data **/*kd*/, dstr */*d*/);
/* --- @key_unpack@ --- *
*
/* --- @key_lock@ --- *
*
- * Arguments: @key_data *kt@ = destination block
- * @key_data *k@ = source key data block
+ * Arguments: @key_data **kt@ = where to store the destination pointer
+ * @key_data *k@ = source key data block or null to use @*kt@
* @const void *e@ = secret to encrypt key with
* @size_t esz@ = size of the secret
*
* Use: Encrypts a key data block using a secret.
*/
-extern void key_lock(key_data */*kt*/, key_data */*k*/,
+extern void key_lock(key_data **/*kt*/, key_data */*k*/,
const void */*e*/, size_t /*esz*/);
/* --- @key_unlock@ --- *
*
- * Arguments: @key_data *kt@ = target block
- * @key_data *k@ = source key data block
+ * Arguments: @key_data **kt@ = where to store the destination pointer
+ * @key_data *k@ = source key data block or null to use @*kt@
* @const void *e@ = secret to decrypt the block with
* @size_t esz@ = size of the secret
*
* Use: Unlocks a key using a secret.
*/
-extern int key_unlock(key_data */*kt*/, key_data */*k*/,
+extern int key_unlock(key_data **/*kt*/, key_data */*k*/,
const void */*e*/, size_t /*esz*/);
/* --- @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
+ * Arguments: @key_data **kt@ = where to store the destination pointer
+ * @key_data *k@ = source key data block or null to use @*kt@
+ * @const char *tag@ = tag to use for passphrase
*
* Returns: Zero if successful, a @KERR@ error code on failure.
*
* Use: Locks a key by encrypting it with a passphrase.
*/
-extern int key_plock(const char */*tag*/, key_data */*k*/, key_data */*kt*/);
+extern int key_plock(key_data **/*kt*/, key_data */*k*/,
+ const char */*tag*/);
/* --- @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
+ * Arguments: @key_data **kt@ = where to store the destination pointer
+ * @key_data *k@ = source key data block or null to use @*kt@
+ * @const char *tag@ = tag to use for passphrase
*
* Returns: Zero if successful, a @KERR@ error code on failure.
*
* Use: Unlocks a passphrase-locked key.
*/
-extern int key_punlock(const char */*tag*/,
- key_data */*k*/, key_data */*kt*/);
+extern int key_punlock(key_data **/*kt*/, key_data */*k*/,
+ const char */*tag*/);
/*----- That's all, folks -------------------------------------------------*/
projects / u / mdw / catacomb / blobdiff