+/*----- 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*/);
+