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

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