catcrypt: Implement symmetric key-encapsulation and signature schemes.

[u/mdw/catacomb] / pixie.h

diff --git a/pixie.h b/pixie.h
index 2ae9e43..25cd86f 100644 (file)
--- a/pixie.h
+++ b/pixie.h
@@ -1,6 +1,6 @@
 /* -*-c-*-
  *
- * $Id: pixie.h,v 1.1 1999/12/22 15:58:41 mdw Exp $
+ * $Id: pixie.h,v 1.3 2004/04/08 01:36:15 mdw Exp $
  *
  * Passphrase pixie definitions (Unix-specific)
  *
@@ -27,14 +27,6 @@
  * MA 02111-1307, USA.
  */
 
-/*----- Revision history --------------------------------------------------* 
- *
- * $Log: pixie.h,v $
- * Revision 1.1  1999/12/22 15:58:41  mdw
- * Passphrase pixie support.
- *
- */
-
 #ifndef CATACOMB_PIXIE_H
 #define CATACOMB_PIXIE_H
 
@@ -78,6 +70,10 @@
  * VERIFY tag [expire]
  *     Request a new passphrase, which therefore requires verification.
  *
+ * SET tag [expire] -- phrase
+ *     Set the value of passphrase `tag'.  This will usually be a follow-up
+ *     to a MISSING response.
+ *
  * FLUSH [tag]
  *     Flush the passphrase named `tag', or all passphrases, from memory.
  *
@@ -90,6 +86,11 @@
  *     Request completed successfully.  If a passphrase was requested, it is
  *     returned by the pixie.  This is the final response to a request.
  *
+ * MISSING
+ *     The passphrase requested is not known, and no requester mechanism is
+ *     present.  The client should request the passphrase itself and pass it
+ *     back to the pixie.  This is the final response to a request.
+ *
  * FAIL error
  *     Reports an error.  The message given is intended to be
  *     human-readable.  This is the final response to a request.
@@ -129,7 +130,8 @@ extern int pixie_open(const char */*sock*/);
  *             @char *buf@ = pointer to destination buffer
  *             @size_t sz@ = size of the buffer
  *
- * Returns:    Zero if all went well, nonzero if the read fails.
+ * Returns:    Zero if all went well, @-1@ if the read fails, @+1@ to
+ *             request the passphrase from the user.
  *
  * Use:                Reads a passphrase from the pixie.
  */
@@ -137,6 +139,20 @@ extern int pixie_open(const char */*sock*/);
 extern int pixie_read(int /*fd*/, const char */*tag*/, unsigned /*mode*/,
                      char */*buf*/, size_t /*sz*/);
 
+/* --- @pixie_set@ --- *
+ *
+ * Arguments:  @int fd@ = pixie file descriptor
+ *             @const char *tag@ = pointer to tag string
+ *             @const char *phrase@ = pointer to passphrase string
+ *
+ * Returns:    ---
+ *
+ * Use:                Sends a passphrase to the passphrase pixie.
+ */
+
+extern void pixie_set(int /*fd*/, const char */*tag*/,
+                     const char */*phrase*/);
+
 /* --- @pixie_cancel@ --- *
  *
  * Arguments:  @int fd@ = pixie file descriptor