chiark - git - mdw - catacomb/blob - pixie.h

   1 /* -*-c-*-
   2  *
   3  * $Id: pixie.h,v 1.3 2004/04/08 01:36:15 mdw Exp $
   4  *
   5  * Passphrase pixie definitions (Unix-specific)
   6  *
   7  * (c) 1999 Straylight/Edgeware
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of Catacomb.
  13  *
  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.
  18  *
  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.
  23  *
  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,
  27  * MA 02111-1307, USA.
  28  */
  29
  30 #ifndef CATACOMB_PIXIE_H
  31 #define CATACOMB_PIXIE_H
  32
  33 #ifdef __cplusplus
  34   extern "C" {
  35 #endif
  36
  37 /*----- Header files ------------------------------------------------------*/
  38
  39 #include <stddef.h>
  40
  41 #include <sys/socket.h>
  42 #include <sys/un.h>
  43
  44 #ifndef CATACOMB_PASSPHRASE_H
  45 #  include "passphrase.h"
  46 #endif
  47
  48 /*----- Protocol definition -----------------------------------------------*
  49  *
  50  * The protocol is simple and text-based.  The client connects to the
  51  * server's socket and sends `request lines', each of which elicits one or
  52  * more `response lines' from the server.  Request and response lines contain
  53  * whitespace-separated fields, and are terminated by a single linefeed.  The
  54  * final field on a line may contain whitespace.  The first field describes
  55  * the type of the line.  The type field is not case-sensitive, although
  56  * writing them in uppercase is conventional.
  57  *
  58  * The requests are:
  59  *
  60  * HELP
  61  *      Provide (very) brief help with the pixie protocol.
  62  *
  63  * LIST
  64  *      Return a list of passphrases currently stored, together with expiry
  65  *      information.
  66  *
  67  * PASS tag [expire]
  68  *      Request the passphrase named `tag' from the pixie.
  69  *
  70  * VERIFY tag [expire]
  71  *      Request a new passphrase, which therefore requires verification.
  72  *
  73  * SET tag [expire] -- phrase
  74  *      Set the value of passphrase `tag'.  This will usually be a follow-up
  75  *      to a MISSING response.
  76  *
  77  * FLUSH [tag]
  78  *      Flush the passphrase named `tag', or all passphrases, from memory.
  79  *
  80  * QUIT
  81  *      Requests that the pixie close down.
  82  *
  83  * Response lines are as follows:
  84  *
  85  * OK [phrase]
  86  *      Request completed successfully.  If a passphrase was requested, it is
  87  *      returned by the pixie.  This is the final response to a request.
  88  *
  89  * MISSING
  90  *      The passphrase requested is not known, and no requester mechanism is
  91  *      present.  The client should request the passphrase itself and pass it
  92  *      back to the pixie.  This is the final response to a request.
  93  *
  94  * FAIL error
  95  *      Reports an error.  The message given is intended to be
  96  *      human-readable.  This is the final response to a request.
  97  *
  98  * INFO message
  99  *      Reports a human-readable informational message.  Further responses
 100  *      follow.
 101  *
 102  * ITEM tag expires
 103  *      Reports a passphrase in response to a LIST request.  One ITEM
 104  *      response is given for each passphrase currently in memory.  An OK or
 105  *      FAIL response follows the last ITEM.
 106  *
 107  * Expiry times in requests may be given in any format acceptable to
 108  * `getdate'.  Expiry times in responses are returned in ISO format
 109  * (YYYY-MM-DD HH:MM:SS ZZZ) and are expressed relative to local time.
 110  */
 111
 112 /*----- Functions provided ------------------------------------------------*/
 113
 114 /* --- @pixie_open@ --- *
 115  *
 116  * Arguments:   @const char *sock@ = path to pixie socket
 117  *
 118  * Returns:     Less than zero if it failed, or file descriptor.
 119  *
 120  * Use:         Opens a connection to a passphrase pixie.
 121  */
 122
 123 extern int pixie_open(const char */*sock*/);
 124
 125 /* --- @pixie_read@ --- *
 126  *
 127  * Arguments:   @int fd@ = connection to passphrase pixie
 128  *              @const char *tag@ = pointer to tag string
 129  *              @unsigned mode@ = reading mode
 130  *              @char *buf@ = pointer to destination buffer
 131  *              @size_t sz@ = size of the buffer
 132  *
 133  * Returns:     Zero if all went well, @-1@ if the read fails, @+1@ to
 134  *              request the passphrase from the user.
 135  *
 136  * Use:         Reads a passphrase from the pixie.
 137  */
 138
 139 extern int pixie_read(int /*fd*/, const char */*tag*/, unsigned /*mode*/,
 140                       char */*buf*/, size_t /*sz*/);
 141
 142 /* --- @pixie_set@ --- *
 143  *
 144  * Arguments:   @int fd@ = pixie file descriptor
 145  *              @const char *tag@ = pointer to tag string
 146  *              @const char *phrase@ = pointer to passphrase string
 147  *
 148  * Returns:     ---
 149  *
 150  * Use:         Sends a passphrase to the passphrase pixie.
 151  */
 152
 153 extern void pixie_set(int /*fd*/, const char */*tag*/,
 154                       const char */*phrase*/);
 155
 156 /* --- @pixie_cancel@ --- *
 157  *
 158  * Arguments:   @int fd@ = pixie file descriptor
 159  *              @const char *tag@ = pointer to tag string
 160  *
 161  * Returns:     ---
 162  *
 163  * Use:         Cancels a passphrase if it turns out to be bogus.
 164  */
 165
 166 extern void pixie_cancel(int /*fd*/, const char */*tag*/);
 167
 168 /* --- @pixie_address@ --- *
 169  *
 170  * Arguments:   @const char *sock@ = pointer to socket name
 171  *              @size_t *psz@ = where to write the address size
 172  *
 173  * Returns:     Pointer to filled-in Unix-domain socket address.
 174  *
 175  * Use:         Returns a Unix-domain socket address to use to find the
 176  *              passphrase pixie.
 177  */
 178
 179 extern struct sockaddr_un *pixie_address(const char */*sock*/,
 180                                          size_t */*psz*/);
 181
 182 /* --- @pixie_fdline@ --- *
 183  *
 184  * Arguments:   @int fd@ = file descriptor to read from
 185  *              @char *buf@ = pointer to buffer
 186  *              @size_t sz@ = size of buffer
 187  *
 188  * Returns:     ---
 189  *
 190  * Use:         Reads a line from a file descriptor.  The read is done one
 191  *              character at a time.  If the entire line won't fit, the end
 192  *              is truncated.  The line is null terminated.
 193  */
 194
 195 extern void pixie_fdline(int /*fd*/, char */*buf*/, size_t /*sz*/);
 196
 197 /* --- @pixie_getpass@ --- *
 198  *
 199  * Arguments:   @const char *prompt@ = pointer to prompt string
 200  *              @char *buf@ = pointer to buffer
 201  *              @size_t sz@ = size of buffer
 202  *
 203  * Returns:     Zero if it worked OK, nonzero otherwise.
 204  *
 205  * Use:         Reads a passphrase from the terminal or some other requested
 206  *              source.
 207  */
 208
 209 extern int pixie_getpass(const char */*prompt*/,
 210                          char */*buf*/, size_t /*sz*/);
 211
 212 /*----- That's all, folks -------------------------------------------------*/
 213
 214 #ifdef __cplusplus
 215   }
 216 #endif
 217
 218 #endif