X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/069c185c6386ddd0a43d3cd4bed99c69884afbfe..e74e12bc7c899a47d3f0e28420f6502b8f70a5a9:/pixie.h

diff --git a/pixie.h b/pixie.h
index 2ae9e43..a5bc171 100644
--- a/pixie.h
+++ b/pixie.h
@@ -1,13 +1,13 @@
 /* -*-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)
  *
  * (c) 1999 Straylight/Edgeware
  */
 
-/*----- Licensing notice --------------------------------------------------* 
+/*----- Licensing notice --------------------------------------------------*
  *
  * This file is part of Catacomb.
  *
@@ -15,26 +15,18 @@
  * 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: 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,13 +86,18 @@
  *	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.
  *
  * INFO message
  *	Reports a human-readable informational message.  Further responses
- *	follow.  
+ *	follow.
  *
  * ITEM tag expires
  *	Reports a passphrase in response to a LIST request.  One ITEM
@@ -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