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 char *(*pwmd_password_fn)(pwm_t *pwm, void *data);
  39 typedef int (*pwmd_status_fn)(void *data, const char *line);
  40
  41 typedef enum {
  42     /*
  43      * PWMD_OPTION_PASSWORD_FUNC
  44      *
  45      * Function to retrieve a password. This function should return an
  46      * string which is the password or NULL on error.
  47      */
  48     PWMD_OPTION_PASSWORD_FUNC,
  49
  50     /*
  51      * PWMD_OPTION_PASSWORD_DATA
  52      *
  53      * Data passed to the password function.
  54      */
  55     PWMD_OPTION_PASSWORD_DATA,
  56
  57     /*
  58      * PWMD_OPTION_PINENTRY
  59      *
  60      * The following argument should be of type int and set to 1 to enable the
  61      * use of pinentry(1) to retrieve passwords. Setting to 0 will disable
  62      * using pinentry and the password must be set with PWMD_OPTION_PASSWORD
  63      * or gotten from PWMD_OPTION_PASSWORD_FUNC.
  64      */
  65     PWMD_OPTION_PINENTRY,
  66
  67     /*
  68      * PWMD_OPTION_PINENTRY_TRIES
  69      *
  70      * The number of password tries before giving up. If the pinentry "Cancel"
  71      * button is selected, pinentry will abort. Must be > 0. The default is 3.
  72      */
  73     PWMD_OPTION_PINENTRY_TRIES,
  74
  75     /*
  76      * PWMD_OPTION_PINENTRY_PATH
  77      *
  78      * The full pathname to the pinentry program. If not specified,
  79      * /usr/bin/pinentry will be used.
  80      */
  81     PWMD_OPTION_PINENTRY_PATH,
  82
  83     /*
  84      * PWMD_OPTION_PINENTRY_TTY
  85      *
  86      * pinentry --ttyname.
  87      */
  88     PWMD_OPTION_PINENTRY_TTY,
  89
  90     /*
  91      * PWMD_OPTION_PINENTRY_DISPLAY
  92      *
  93      * pinentry --display
  94      */
  95     PWMD_OPTION_PINENTRY_DISPLAY,
  96
  97     /*
  98      * PWMD_OPTION_PINENTRY_TERM
  99      *
 100      * pinentry --ttytype
 101      */
 102     PWMD_OPTION_PINENTRY_TERM,
 103
 104     /*
 105      * PWMD_OPTION_PASSWORD
 106      *
 107      * The following argument should be of type char* which specifies the
 108      * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and
 109      * PWMD_OPTION_PINENTRY is 0. The password will be kept in memory until
 110      * pwmd_close() is called so setting this option isn't needed each time
 111      * pwmd_open() or pwmd_save() is called reguardless of pwmd cache
 112      * settings.
 113      */
 114     PWMD_OPTION_PASSWORD,
 115
 116     /*
 117      * PWMD_OPTION_PINENTRY_TITLE
 118      * PWMD_OPTION_PINENTRY_PROMPT
 119      * PWMD_OPTION_PINENTRY_DESC
 120      *
 121      * The following argument is of type char* which specifies either the
 122      * title, prompt or description in the pinentry program when
 123      * PWMD_OPTION_PINENTRY is set.
 124      */
 125      PWMD_OPTION_PINENTRY_TITLE,
 126      PWMD_OPTION_PINENTRY_PROMPT,
 127      PWMD_OPTION_PINENTRY_DESC,
 128
 129      /*
 130       * PWMD_OPTION_STATUS_FUNC
 131       *
 132       * A function to be called when a status line is sent from pwmd. This
 133       * function should return 0 on success or a gpg-error error code. This
 134       * function won't be used when getting a password with pinentry.
 135       */
 136      PWMD_OPTION_STATUS_FUNC,
 137
 138      /*
 139       * PWMD_OPTION_STATUS_DATA
 140       *
 141       * Data passed to the status function.
 142       */
 143      PWMD_OPTION_STATUS_DATA,
 144 } pwmd_option_t;
 145
 146 /*
 147  * Initialize the library.
 148  */
 149 gpg_error_t pwmd_init(void);
 150
 151 /*
 152  * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
 153  * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
 154  * with the other functions or NULL if there was an error in which case
 155  * 'error' is set to an error code which may be described by pwmd_strerror().
 156  */
 157 pwm_t *pwmd_connect(const char *socket_path, gpg_error_t *error) __attribute__ ((warn_unused_result));
 158
 159 /*
 160  * Opens a file 'filename' (the OPEN command). The password is gotten from the
 161  * pinentry program if configured to do so and not already cached. Returnes
 162  * 0 on success or an error code.
 163  */
 164 gpg_error_t pwmd_open(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result));
 165
 166 /*
 167  * This a nonblocking way of opening a file. It returns -2 when the file is
 168  * cached (ISCACHED) on the server or if the file doesn't exist on the file
 169  * system (a new file). Otherwise it returns a file descriptor that select()
 170  * can use. When ready for a read, read() should read a pwmd_nb_status_t. If
 171  * there is a system error (pipe() or fork()), then -1 is returned and 'error'
 172  * is set to an error code that pwmd_strerror() can describe.
 173  *
 174  * When a file descriptor has been returned from pwmd_open_nb() and after a
 175  * successful read(), the caller should use pwmd_open_nb_finalize() to update
 176  * the 'pwm' handle. If there was a pinentry or protocol error
 177  * pwmd_open_nb_finalize() will return an error code or 0 on success.
 178  *
 179  * The 'timeout' parameter specifies the number of seconds until the pinentry
 180  * terminates. Setting to 0 (the default) will disable timeouts. Note that the
 181  * child process will reset the SIGALRM handler (if any) to it's own handler
 182  * and that the actual OPEN command isn't calculated as part of the elapsed
 183  * time.
 184  *
 185  * Be sure to set PWMD_OPTION_PINENTRY.
 186  */
 187 int pwmd_open_nb(pwm_t *pwm, gpg_error_t *error, const char *filename, int timeout) __attribute__ ((warn_unused_result));
 188 gpg_error_t pwmd_open_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 189
 190 /*
 191  * Send's the SAVE command and takes care of password requests.
 192  */
 193 gpg_error_t pwmd_save(pwm_t *pwm) __attribute__ ((warn_unused_result));
 194
 195 /*
 196  * Send's the SAVE protocol command without pinentry blocking the process. It
 197  * act's like pwmd_open_nb() above, but doesn't require a filename. The caller
 198  * should use pwmd_save_nb_finalize() when a file descriptor is returned from
 199  * pwmd_save_nb() and after a successful read().
 200  *
 201  * Be sure to set PWMD_OPTION_PINENTRY.
 202  */
 203 int pwmd_save_nb(pwm_t *pwm, gpg_error_t *error) __attribute__ ((warn_unused_result));
 204 gpg_error_t pwmd_save_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 205
 206 /*
 207  * Terminates a pinentry process. If your not using pwmd_open_nb() and want to
 208  * timeout a password entry, then call this function after your timer has
 209  * expired. Returns 0 on success or an error code.
 210  */
 211 gpg_error_t pwmd_terminate_pinentry(pwm_t *pwm) __attribute__ ((warn_unused_result));
 212
 213 /*
 214  * Closes the connection to the socket and frees the resources of the handle.
 215  * Returns no value.
 216  */
 217 void pwmd_close(pwm_t *pwm);
 218
 219 /*
 220  * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
 221  * command fails an error code is returned which may be described by passing
 222  * the error to pwmd_strerror(). If successful the function returns 0 and the
 223  * 'result' is the character data of the command or NULL if there was none.
 224  *
 225  * A note about the BYE command: Client's should not send this command
 226  * directly with pwmd_command(). They should use pwmd_close() instead because
 227  * libassuan will close the file descriptors with the associated context. This
 228  * is fine except when pwmd_close() is called. pwmd_close() calls
 229  * assuan_disconnect() which then send's the BYE command to the closed file
 230  * descriptor resulting in a segfault.
 231  */
 232 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...) __attribute__ ((warn_unused_result));
 233
 234 /*
 235  * Free's the memory used by the result of pwmd_command() if any. It is
 236  * important to use this function because libpwmd keeps track of all memory
 237  * de/allocations.
 238  */
 239 void pwmd_free_result(void *);
 240
 241 /*
 242  * Sets a libpwmd option 'opt'. The next argument should be of the data type
 243  * required for the option. Returns 0 on success or an error code.
 244  */
 245 gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...) __attribute__ ((warn_unused_result));
 246
 247 /*
 248  * Protocol error codes.
 249  */
 250 #define EPWMD_ERROR             GPG_ERR_USER_1
 251 #define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
 252 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_USER_3
 253 #define EPWMD_TRAILING_ELEMENT  GPG_ERR_USER_4
 254 #define EPWMD_INVALID_ELEMENT   GPG_ERR_USER_5
 255 #define EPWMD_EMPTY_ELEMENT     GPG_ERR_USER_6
 256 #define EPWMD_ACCOUNT_EXISTS    GPG_ERR_USER_7
 257 #define EPWMD_FILE_NOT_FOUND    GPG_ERR_USER_8
 258 #define EPWMD_NO_FILE           GPG_ERR_USER_9
 259 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_10
 260 #define EPWMD_CACHE_NOT_FOUND   GPG_ERR_USER_11
 261 #define EPWMD_ATTR_NOT_FOUND    GPG_ERR_USER_12
 262 #define EPWMD_INVALID_FILENAME  GPG_ERR_USER_13
 263 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_14
 264 #define EPWMD_MAX               GPG_ERR_USER_15
 265
 266 /*
 267  * Try to reuse GPG error codes when possible. There's only 16 user-defined
 268  * codes available.
 269  */
 270 #define EPWMD_KEY               GPG_ERR_WRONG_KEY_USAGE
 271 #define EPWMD_BADKEY            GPG_ERR_INV_PASSPHRASE
 272 #define EPWMD_COMMAND_SYNTAX    GPG_ERR_SYNTAX
 273 #define EPWMD_ATTR_SYNTAX       GPG_ERR_SYNTAX
 274
 275 /*
 276  * Return a string describing a pwmd protocol error code.
 277  */
 278 const char *pwmd_strerror(gpg_error_t error);
 279
 280 #ifdef __cplusplus
 281 }
 282 #endif
 283
 284 #endif