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

   1 /* -*-c-*-
   2  *
   3  * $Id: pixie.h,v 1.2 2000/06/17 11:49:49 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 /*----- Revision history --------------------------------------------------*
  31  *
  32  * $Log: pixie.h,v $
  33  * Revision 1.2  2000/06/17 11:49:49  mdw
  34  * New pixie protocol allowing application to request passphrases and send
  35  * them to the pixie.
  36  *
  37  * Revision 1.1  1999/12/22 15:58:41  mdw
  38  * Passphrase pixie support.
  39  *
  40  */
  41
  42 #ifndef CATACOMB_PIXIE_H
  43 #define CATACOMB_PIXIE_H
  44
  45 #ifdef __cplusplus
  46   extern "C" {
  47 #endif
  48
  49 /*----- Header files ------------------------------------------------------*/
  50
  51 #include <stddef.h>
  52
  53 #include <sys/socket.h>
  54 #include <sys/un.h>
  55
  56 #ifndef CATACOMB_PASSPHRASE_H
  57 #  include "passphrase.h"
  58 #endif
  59
  60 /*----- Protocol definition -----------------------------------------------*
  61  *
  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.
  69  *
  70  * The requests are:
  71  *
  72  * HELP
  73  *      Provide (very) brief help with the pixie protocol.
  74  *
  75  * LIST
  76  *      Return a list of passphrases currently stored, together with expiry
  77  *      information.
  78  *
  79  * PASS tag [expire]
  80  *      Request the passphrase named `tag' from the pixie.
  81  *
  82  * VERIFY tag [expire]
  83  *      Request a new passphrase, which therefore requires verification.
  84  *
  85  * SET tag [expire] -- phrase
  86  *      Set the value of passphrase `tag'.  This will usually be a follow-up
  87  *      to a MISSING response.
  88  *
  89  * FLUSH [tag]
  90  *      Flush the passphrase named `tag', or all passphrases, from memory.
  91  *
  92  * QUIT
  93  *      Requests that the pixie close down.
  94  *
  95  * Response lines are as follows:
  96  *
  97  * OK [phrase]
  98  *      Request completed successfully.  If a passphrase was requested, it is
  99  *      returned by the pixie.  This is the final response to a request.
 100  *
 101  * MISSING
 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.
 105  *
 106  * FAIL error
 107  *      Reports an error.  The message given is intended to be
 108  *      human-readable.  This is the final response to a request.
 109  *
 110  * INFO message
 111  *      Reports a human-readable informational message.  Further responses
 112  *      follow.
 113  *
 114  * ITEM tag expires
 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.
 118  *
 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.
 122  */
 123
 124 /*----- Functions provided ------------------------------------------------*/
 125
 126 /* --- @pixie_open@ --- *
 127  *
 128  * Arguments:   @const char *sock@ = path to pixie socket
 129  *
 130  * Returns:     Less than zero if it failed, or file descriptor.
 131  *
 132  * Use:         Opens a connection to a passphrase pixie.
 133  */
 134
 135 extern int pixie_open(const char */*sock*/);
 136
 137 /* --- @pixie_read@ --- *
 138  *
 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
 144  *
 145  * Returns:     Zero if all went well, @-1@ if the read fails, @+1@ to
 146  *              request the passphrase from the user.
 147  *
 148  * Use:         Reads a passphrase from the pixie.
 149  */
 150
 151 extern int pixie_read(int /*fd*/, const char */*tag*/, unsigned /*mode*/,
 152                       char */*buf*/, size_t /*sz*/);
 153
 154 /* --- @pixie_set@ --- *
 155  *
 156  * Arguments:   @int fd@ = pixie file descriptor
 157  *              @const char *tag@ = pointer to tag string
 158  *              @const char *phrase@ = pointer to passphrase string
 159  *
 160  * Returns:     ---
 161  *
 162  * Use:         Sends a passphrase to the passphrase pixie.
 163  */
 164
 165 extern void pixie_set(int /*fd*/, const char */*tag*/,
 166                       const char */*phrase*/);
 167
 168 /* --- @pixie_cancel@ --- *
 169  *
 170  * Arguments:   @int fd@ = pixie file descriptor
 171  *              @const char *tag@ = pointer to tag string
 172  *
 173  * Returns:     ---
 174  *
 175  * Use:         Cancels a passphrase if it turns out to be bogus.
 176  */
 177
 178 extern void pixie_cancel(int /*fd*/, const char */*tag*/);
 179
 180 /* --- @pixie_address@ --- *
 181  *
 182  * Arguments:   @const char *sock@ = pointer to socket name
 183  *              @size_t *psz@ = where to write the address size
 184  *
 185  * Returns:     Pointer to filled-in Unix-domain socket address.
 186  *
 187  * Use:         Returns a Unix-domain socket address to use to find the
 188  *              passphrase pixie.
 189  */
 190
 191 extern struct sockaddr_un *pixie_address(const char */*sock*/,
 192                                          size_t */*psz*/);
 193
 194 /* --- @pixie_fdline@ --- *
 195  *
 196  * Arguments:   @int fd@ = file descriptor to read from
 197  *              @char *buf@ = pointer to buffer
 198  *              @size_t sz@ = size of buffer
 199  *
 200  * Returns:     ---
 201  *
 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.
 205  */
 206
 207 extern void pixie_fdline(int /*fd*/, char */*buf*/, size_t /*sz*/);
 208
 209 /* --- @pixie_getpass@ --- *
 210  *
 211  * Arguments:   @const char *prompt@ = pointer to prompt string
 212  *              @char *buf@ = pointer to buffer
 213  *              @size_t sz@ = size of buffer
 214  *
 215  * Returns:     Zero if it worked OK, nonzero otherwise.
 216  *
 217  * Use:         Reads a passphrase from the terminal or some other requested
 218  *              source.
 219  */
 220
 221 extern int pixie_getpass(const char */*prompt*/,
 222                          char */*buf*/, size_t /*sz*/);
 223
 224 /*----- That's all, folks -------------------------------------------------*/
 225
 226 #ifdef __cplusplus
 227   }
 228 #endif
 229
 230 #endif