3 * $Id: pixie.h,v 1.2 2000/06/17 11:49:49 mdw Exp $
5 * Passphrase pixie definitions (Unix-specific)
7 * (c) 1999 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of Catacomb.
14 * Catacomb is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU Library General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
19 * Catacomb is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU Library General Public License for more details.
24 * You should have received a copy of the GNU Library General Public
25 * License along with Catacomb; if not, write to the Free
26 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
30 /*----- Revision history --------------------------------------------------*
33 * Revision 1.2 2000/06/17 11:49:49 mdw
34 * New pixie protocol allowing application to request passphrases and send
37 * Revision 1.1 1999/12/22 15:58:41 mdw
38 * Passphrase pixie support.
42 #ifndef CATACOMB_PIXIE_H
43 #define CATACOMB_PIXIE_H
49 /*----- Header files ------------------------------------------------------*/
53 #include <sys/socket.h>
56 #ifndef CATACOMB_PASSPHRASE_H
57 # include "passphrase.h"
60 /*----- Protocol definition -----------------------------------------------*
62 * The protocol is simple and text-based. The client connects to the
63 * server's socket and sends `request lines', each of which elicits one or
64 * more `response lines' from the server. Request and response lines contain
65 * whitespace-separated fields, and are terminated by a single linefeed. The
66 * final field on a line may contain whitespace. The first field describes
67 * the type of the line. The type field is not case-sensitive, although
68 * writing them in uppercase is conventional.
73 * Provide (very) brief help with the pixie protocol.
76 * Return a list of passphrases currently stored, together with expiry
80 * Request the passphrase named `tag' from the pixie.
83 * Request a new passphrase, which therefore requires verification.
85 * SET tag [expire] -- phrase
86 * Set the value of passphrase `tag'. This will usually be a follow-up
87 * to a MISSING response.
90 * Flush the passphrase named `tag', or all passphrases, from memory.
93 * Requests that the pixie close down.
95 * Response lines are as follows:
98 * Request completed successfully. If a passphrase was requested, it is
99 * returned by the pixie. This is the final response to a request.
102 * The passphrase requested is not known, and no requester mechanism is
103 * present. The client should request the passphrase itself and pass it
104 * back to the pixie. This is the final response to a request.
107 * Reports an error. The message given is intended to be
108 * human-readable. This is the final response to a request.
111 * Reports a human-readable informational message. Further responses
115 * Reports a passphrase in response to a LIST request. One ITEM
116 * response is given for each passphrase currently in memory. An OK or
117 * FAIL response follows the last ITEM.
119 * Expiry times in requests may be given in any format acceptable to
120 * `getdate'. Expiry times in responses are returned in ISO format
121 * (YYYY-MM-DD HH:MM:SS ZZZ) and are expressed relative to local time.
124 /*----- Functions provided ------------------------------------------------*/
126 /* --- @pixie_open@ --- *
128 * Arguments: @const char *sock@ = path to pixie socket
130 * Returns: Less than zero if it failed, or file descriptor.
132 * Use: Opens a connection to a passphrase pixie.
135 extern int pixie_open(const char */
*sock*/
);
137 /* --- @pixie_read@ --- *
139 * Arguments: @int fd@ = connection to passphrase pixie
140 * @const char *tag@ = pointer to tag string
141 * @unsigned mode@ = reading mode
142 * @char *buf@ = pointer to destination buffer
143 * @size_t sz@ = size of the buffer
145 * Returns: Zero if all went well, @-1@ if the read fails, @+1@ to
146 * request the passphrase from the user.
148 * Use: Reads a passphrase from the pixie.
151 extern int pixie_read(int /*fd*/, const char */
*tag*/
, unsigned /*mode*/,
152 char */
*buf*/
, size_t /*sz*/);
154 /* --- @pixie_set@ --- *
156 * Arguments: @int fd@ = pixie file descriptor
157 * @const char *tag@ = pointer to tag string
158 * @const char *phrase@ = pointer to passphrase string
162 * Use: Sends a passphrase to the passphrase pixie.
165 extern void pixie_set(int /*fd*/, const char */
*tag*/
,
166 const char */
*phrase*/
);
168 /* --- @pixie_cancel@ --- *
170 * Arguments: @int fd@ = pixie file descriptor
171 * @const char *tag@ = pointer to tag string
175 * Use: Cancels a passphrase if it turns out to be bogus.
178 extern void pixie_cancel(int /*fd*/, const char */
*tag*/
);
180 /* --- @pixie_address@ --- *
182 * Arguments: @const char *sock@ = pointer to socket name
183 * @size_t *psz@ = where to write the address size
185 * Returns: Pointer to filled-in Unix-domain socket address.
187 * Use: Returns a Unix-domain socket address to use to find the
191 extern struct sockaddr_un
*pixie_address(const char */
*sock*/
,
194 /* --- @pixie_fdline@ --- *
196 * Arguments: @int fd@ = file descriptor to read from
197 * @char *buf@ = pointer to buffer
198 * @size_t sz@ = size of buffer
202 * Use: Reads a line from a file descriptor. The read is done one
203 * character at a time. If the entire line won't fit, the end
204 * is truncated. The line is null terminated.
207 extern void pixie_fdline(int /*fd*/, char */
*buf*/
, size_t /*sz*/);
209 /* --- @pixie_getpass@ --- *
211 * Arguments: @const char *prompt@ = pointer to prompt string
212 * @char *buf@ = pointer to buffer
213 * @size_t sz@ = size of buffer
215 * Returns: Zero if it worked OK, nonzero otherwise.
217 * Use: Reads a passphrase from the terminal or some other requested
221 extern int pixie_getpass(const char */
*prompt*/
,
222 char */
*buf*/
, size_t /*sz*/);
224 /*----- That's all, folks -------------------------------------------------*/