libpwmd.h

   1 /* vim:tw=78:ts=8:sw=4:set ft=c:  */
   2 /*
   3     Copyright (C) 2006-2007 Ben Kibbey <bjk@luxsci.net>
   4
   5     This program is free software; you can redistribute it and/or modify
   6     it under the terms of the GNU General Public License as published by
   7     the Free Software Foundation; either version 2 of the License, or
   8     (at your option) any later version.
   9
  10     This program is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13     GNU General Public License for more details.
  14
  15     You should have received a copy of the GNU General Public License
  16     along with this program; if not, write to the Free Software
  17     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18 */
  19 #ifndef LIBPWMD_H
  20 #define LIBPWMD_H
  21
  22 #include <assuan.h>
  23 #include <gpg-error.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 struct pwm_s;
  30 typedef struct pwm_s pwm_t;
  31
  32 typedef struct {
  33     char filename[FILENAME_MAX];
  34     int fd;
  35     gpg_error_t error;
  36 } pwmd_nb_status_t;
  37
  38 typedef enum {
  39     PWMD_OK,
  40     PWMD_ERROR,
  41 } pwmd_error_t;
  42
  43 typedef char *(*pwmd_password_fn)(pwm_t *pwm, void *data);
  44 typedef int (*pwmd_status_fn)(void *data, const char *line);
  45
  46 typedef enum {
  47     /*
  48      * PWMD_OPTION_PASSWORD_FUNC
  49      *
  50      * Function to retrieve a password. This function should return an
  51      * string which is the password or NULL on error.
  52      */
  53     PWMD_OPTION_PASSWORD_FUNC,
  54
  55     /*
  56      * PWMD_OPTION_PASSWORD_DATA
  57      *
  58      * Data passed to the password function.
  59      */
  60     PWMD_OPTION_PASSWORD_DATA,
  61
  62     /*
  63      * PWMD_OPTION_PINENTRY
  64      *
  65      * The following argument should be of type int and set to 1 to enable the
  66      * use of pinentry(1) to retrieve passwords. Setting to 0 will disable
  67      * using pinentry and the password must be set with PWMD_OPTION_PASSWORD
  68      * or gotten from PWMD_OPTION_PASSWORD_FUNC.
  69      */
  70     PWMD_OPTION_PINENTRY,
  71
  72     /*
  73      * PWMD_OPTION_PINENTRY_TRIES
  74      *
  75      * The number of password tries before giving up. If the pinentry "Cancel"
  76      * button is selected, pinentry will abort. Must be > 0. The default is 3.
  77      */
  78     PWMD_OPTION_PINENTRY_TRIES,
  79
  80     /*
  81      * PWMD_OPTION_PINENTRY_PATH
  82      *
  83      * The full pathname to the pinentry program. If not specified,
  84      * /usr/bin/pinentry will be used.
  85      */
  86     PWMD_OPTION_PINENTRY_PATH,
  87
  88     /*
  89      * PWMD_OPTION_PINENTRY_TTY
  90      *
  91      * pinentry --ttyname.
  92      */
  93     PWMD_OPTION_PINENTRY_TTY,
  94
  95     /*
  96      * PWMD_OPTION_PINENTRY_DISPLAY
  97      *
  98      * pinentry --display
  99      */
 100     PWMD_OPTION_PINENTRY_DISPLAY,
 101
 102     /*
 103      * PWMD_OPTION_PINENTRY_TERM
 104      *
 105      * pinentry --ttytype
 106      */
 107     PWMD_OPTION_PINENTRY_TERM,
 108
 109     /*
 110      * PWMD_OPTION_PASSWORD
 111      *
 112      * The following argument should be of type char* which specifies the
 113      * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and
 114      * PWMD_OPTION_PINENTRY is 0.
 115      */
 116     PWMD_OPTION_PASSWORD,
 117
 118     /*
 119      * PWMD_OPTION_PINENTRY_TITLE
 120      * PWMD_OPTION_PINENTRY_PROMPT
 121      * PWMD_OPTION_PINENTRY_DESC
 122      *
 123      * The following argument is of type char* which specifies either the
 124      * title, prompt or description in the pinentry program when
 125      * PWMD_OPTION_PINENTRY is set.
 126      */
 127      PWMD_OPTION_PINENTRY_TITLE,
 128      PWMD_OPTION_PINENTRY_PROMPT,
 129      PWMD_OPTION_PINENTRY_DESC,
 130
 131      /*
 132       * PWMD_OPTION_STATUS_FUNC
 133       *
 134       * A function to be called when a status line is sent from pwmd. This
 135       * function should return 0 on success or a gpg-error error code. This
 136       * function won't be used when getting a password with pinentry.
 137       */
 138      PWMD_OPTION_STATUS_FUNC,
 139
 140      /*
 141       * PWMD_OPTION_STATUS_DATA
 142       *
 143       * Data passed to the status function.
 144       */
 145      PWMD_OPTION_STATUS_DATA,
 146 } pwmd_option_t;
 147
 148 /*
 149  * Initialize the library.
 150  */
 151 pwmd_error_t pwmd_init(void);
 152
 153 /*
 154  * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
 155  * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
 156  * with the other functions or NULL if there was an error in which case
 157  * 'error' is set to an error code which may be described by pwmd_strerror().
 158  */
 159 pwm_t *pwmd_connect(const char *socket_path, gpg_error_t *error);
 160
 161 /*
 162  * Opens a file 'filename' (the OPEN command). The password is gotten from the
 163  * pinentry program if configured to do so and not already cached. Returnes
 164  * PWMD_OK on success or PWMD_ERROR on error and sets 'error' to the error
 165  * code.
 166  */
 167 pwmd_error_t pwmd_open(pwm_t *pwm, gpg_error_t *error, const char *filename);
 168
 169 /*
 170  * This a nonblocking way of opening a file. It returns -2 when the file is
 171  * cached (ISCACHED) on the server or if the file doesn't exist on the file
 172  * system (a new file). Otherwise it returns a file descriptor that select()
 173  * can use. When ready for a read, read() should read a pwmd_nb_status_t. If
 174  * there is a system error (pipe() or fork()), then -1 is returned and 'error'
 175  * is set to an error code that pwmd_strerror() can describe.
 176  *
 177  * When a file descriptor has been returned from pwmd_open_nb() and after a
 178  * successful read(), the caller should use pwmd_open_nb_finalize() to update
 179  * the 'pwm' handle. If there was a pinentry or protocol error
 180  * pwmd_open_nb_finalize() will set 'error' to the error code.
 181  *
 182  * Be sure to set PWMD_OPTION_PINENTRY.
 183  */
 184 int pwmd_open_nb(pwm_t *pwm, gpg_error_t *error, const char *filename);
 185 pwmd_error_t pwmd_open_nb_finalize(pwm_t *pwm, gpg_error_t *error, pwmd_nb_status_t *status);
 186
 187 /*
 188  * Send's the SAVE command and takes care of password requests.
 189  */
 190 pwmd_error_t pwmd_save(pwm_t *pwm, gpg_error_t *error);
 191
 192 /*
 193  * Send's the SAVE protocol command without pinentry blocking the process. It
 194  * act's like pwmd_open_nb() above, but doesn't require a filename. The caller
 195  * should use pwmd_save_nb_finalize() when a file descriptor is returned from
 196  * pwmd_save_nb() and after a successful read().
 197  *
 198  * Be sure to set PWMD_OPTION_PINENTRY.
 199  */
 200 int pwmd_save_nb(pwm_t *pwm, gpg_error_t *error);
 201 pwmd_error_t pwmd_save_nb_finalize(pwm_t *pwm, gpg_error_t *error, pwmd_nb_status_t *status);
 202
 203 /*
 204  * Closes the connection to the socket and frees the resources of the handle.
 205  * Returns no value.
 206  */
 207 void pwmd_close(pwm_t *pwm);
 208
 209 /*
 210  * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
 211  * command fails PWMD_ERROR is returned with 'error' set to the error code
 212  * which may be described by passing the error to pwmd_strerror(). If
 213  * successful the function returns PWMD_OK and the 'result' is the character
 214  * data of the command or NULL if there was none.
 215  *
 216  * A note about the BYE command: Client's should not send this command
 217  * directly with pwmd_command(). They should use pwmd_close() instead because
 218  * libassuan will close the file descriptors with the associated context. This
 219  * is fine except when pwmd_close() is called. pwmd_close() calls
 220  * assuan_disconnect() which then send's the BYE command to the closed file
 221  * descriptor resulting in a segfault.
 222  */
 223 pwmd_error_t pwmd_command(pwm_t *pwm, char **result, gpg_error_t *error, const char *cmd, ...);
 224
 225 /*
 226  * Free's the memory used by the result of pwmd_command() if any. It is
 227  * important to use this function because libpwmd keeps track of all memory
 228  * de/allocations.
 229  */
 230 void pwmd_free_result(void *);
 231
 232 /*
 233  * Sets a libpwmd option 'opt'. The next argument should be of the data type
 234  * required for the option. Return PWMD_OK on success or PWMD_ERROR if 'opt'
 235  * is an invalid option.
 236  */
 237 pwmd_error_t pwmd_setopt(pwm_t *pwm, gpg_error_t *error, pwmd_option_t opt, ...);
 238
 239 /*
 240  * Protocol error codes.
 241  */
 242 #define EPWMD_ERROR             GPG_ERR_USER_1
 243 #define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
 244 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_USER_3
 245 #define EPWMD_TRAILING_ELEMENT  GPG_ERR_USER_4
 246 #define EPWMD_INVALID_ELEMENT   GPG_ERR_USER_5
 247 #define EPWMD_EMPTY_ELEMENT     GPG_ERR_USER_6
 248 #define EPWMD_ACCOUNT_EXISTS    GPG_ERR_USER_7
 249 #define EPWMD_FILE_NOT_FOUND    GPG_ERR_USER_8
 250 #define EPWMD_NO_FILE           GPG_ERR_USER_9
 251 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_10
 252 #define EPWMD_CACHE_NOT_FOUND   GPG_ERR_USER_11
 253 #define EPWMD_ATTR_NOT_FOUND    GPG_ERR_USER_12
 254 #define EPWMD_INVALID_FILENAME  GPG_ERR_USER_13
 255 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_14
 256 #define EPWMD_MAX               GPG_ERR_USER_15
 257
 258 /*
 259  * Try to reuse GPG error codes when possible. There's only 16 user-defined
 260  * codes available.
 261  */
 262 #define EPWMD_KEY               GPG_ERR_WRONG_KEY_USAGE
 263 #define EPWMD_BADKEY            GPG_ERR_INV_PASSPHRASE
 264 #define EPWMD_COMMAND_SYNTAX    GPG_ERR_SYNTAX
 265 #define EPWMD_ATTR_SYNTAX       GPG_ERR_SYNTAX
 266
 267 /*
 268  * Return a string describing a pwmd protocol error code.
 269  */
 270 const char *pwmd_strerror(gpg_error_t error);
 271
 272 #ifdef __cplusplus
 273 }
 274 #endif
 275
 276 #endif