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.
 110      */
 111     PWMD_OPTION_PASSWORD,
 112
 113     /*
 114      * PWMD_OPTION_PINENTRY_TITLE
 115      * PWMD_OPTION_PINENTRY_PROMPT
 116      * PWMD_OPTION_PINENTRY_DESC
 117      *
 118      * The following argument is of type char* which specifies either the
 119      * title, prompt or description in the pinentry program when
 120      * PWMD_OPTION_PINENTRY is set.
 121      */
 122      PWMD_OPTION_PINENTRY_TITLE,
 123      PWMD_OPTION_PINENTRY_PROMPT,
 124      PWMD_OPTION_PINENTRY_DESC,
 125
 126      /*
 127       * PWMD_OPTION_STATUS_FUNC
 128       *
 129       * A function to be called when a status line is sent from pwmd. This
 130       * function should return 0 on success or a gpg-error error code. This
 131       * function won't be used when getting a password with pinentry.
 132       */
 133      PWMD_OPTION_STATUS_FUNC,
 134
 135      /*
 136       * PWMD_OPTION_STATUS_DATA
 137       *
 138       * Data passed to the status function.
 139       */
 140      PWMD_OPTION_STATUS_DATA,
 141 } pwmd_option_t;
 142
 143 /*
 144  * Initialize the library.
 145  */
 146 gpg_error_t pwmd_init(void);
 147
 148 /*
 149  * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
 150  * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
 151  * with the other functions or NULL if there was an error in which case
 152  * 'error' is set to an error code which may be described by pwmd_strerror().
 153  */
 154 pwm_t *pwmd_connect(const char *socket_path, gpg_error_t *error) __attribute__ ((warn_unused_result));
 155
 156 /*
 157  * Opens a file 'filename' (the OPEN command). The password is gotten from the
 158  * pinentry program if configured to do so and not already cached. Returnes
 159  * 0 on success or an error code.
 160  */
 161 gpg_error_t pwmd_open(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result));
 162
 163 /*
 164  * This a nonblocking way of opening a file. It returns -2 when the file is
 165  * cached (ISCACHED) on the server or if the file doesn't exist on the file
 166  * system (a new file). Otherwise it returns a file descriptor that select()
 167  * can use. When ready for a read, read() should read a pwmd_nb_status_t. If
 168  * there is a system error (pipe() or fork()), then -1 is returned and 'error'
 169  * is set to an error code that pwmd_strerror() can describe.
 170  *
 171  * When a file descriptor has been returned from pwmd_open_nb() and after a
 172  * successful read(), the caller should use pwmd_open_nb_finalize() to update
 173  * the 'pwm' handle. If there was a pinentry or protocol error
 174  * pwmd_open_nb_finalize() will return an error code or 0 on success.
 175  *
 176  * The 'timeout' parameter specifies the number of seconds until the pinentry
 177  * terminates. Setting to 0 (the default) will disable timeouts. Note that the
 178  * child process will reset the SIGALRM handler (if any) to it's own handler
 179  * and that the actual OPEN command isn't calculated as part of the elapsed
 180  * time.
 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, int timeout) __attribute__ ((warn_unused_result));
 185 gpg_error_t pwmd_open_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 186
 187 /*
 188  * Send's the SAVE command and takes care of password requests.
 189  */
 190 gpg_error_t pwmd_save(pwm_t *pwm) __attribute__ ((warn_unused_result));
 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) __attribute__ ((warn_unused_result));
 201 gpg_error_t pwmd_save_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 202
 203 /*
 204  * Terminates a pinentry process. If your not using pwmd_open_nb() and want to
 205  * timeout a password entry, then call this function after your timer has
 206  * expired. Returns 0 on success or an error code.
 207  */
 208 gpg_error_t pwmd_terminate_pinentry(pwm_t *pwm) __attribute__ ((warn_unused_result));
 209
 210 /*
 211  * Closes the connection to the socket and frees the resources of the handle.
 212  * Returns no value.
 213  */
 214 void pwmd_close(pwm_t *pwm);
 215
 216 /*
 217  * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
 218  * command fails an error code is returned which may be described by passing
 219  * the error to pwmd_strerror(). If successful the function returns 0 and the
 220  * 'result' is the character data of the command or NULL if there was none.
 221  *
 222  * A note about the BYE command: Client's should not send this command
 223  * directly with pwmd_command(). They should use pwmd_close() instead because
 224  * libassuan will close the file descriptors with the associated context. This
 225  * is fine except when pwmd_close() is called. pwmd_close() calls
 226  * assuan_disconnect() which then send's the BYE command to the closed file
 227  * descriptor resulting in a segfault.
 228  */
 229 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...) __attribute__ ((warn_unused_result));
 230
 231 /*
 232  * Free's the memory used by the result of pwmd_command() if any. It is
 233  * important to use this function because libpwmd keeps track of all memory
 234  * de/allocations.
 235  */
 236 void pwmd_free_result(void *);
 237
 238 /*
 239  * Sets a libpwmd option 'opt'. The next argument should be of the data type
 240  * required for the option. Returns 0 on success or an error code.
 241  */
 242 gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...) __attribute__ ((warn_unused_result));
 243
 244 /*
 245  * Protocol error codes.
 246  */
 247 #define EPWMD_ERROR             GPG_ERR_USER_1
 248 #define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
 249 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_USER_3
 250 #define EPWMD_TRAILING_ELEMENT  GPG_ERR_USER_4
 251 #define EPWMD_INVALID_ELEMENT   GPG_ERR_USER_5
 252 #define EPWMD_EMPTY_ELEMENT     GPG_ERR_USER_6
 253 #define EPWMD_ACCOUNT_EXISTS    GPG_ERR_USER_7
 254 #define EPWMD_FILE_NOT_FOUND    GPG_ERR_USER_8
 255 #define EPWMD_NO_FILE           GPG_ERR_USER_9
 256 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_10
 257 #define EPWMD_CACHE_NOT_FOUND   GPG_ERR_USER_11
 258 #define EPWMD_ATTR_NOT_FOUND    GPG_ERR_USER_12
 259 #define EPWMD_INVALID_FILENAME  GPG_ERR_USER_13
 260 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_14
 261 #define EPWMD_MAX               GPG_ERR_USER_15
 262
 263 /*
 264  * Try to reuse GPG error codes when possible. There's only 16 user-defined
 265  * codes available.
 266  */
 267 #define EPWMD_KEY               GPG_ERR_WRONG_KEY_USAGE
 268 #define EPWMD_BADKEY            GPG_ERR_INV_PASSPHRASE
 269 #define EPWMD_COMMAND_SYNTAX    GPG_ERR_SYNTAX
 270 #define EPWMD_ATTR_SYNTAX       GPG_ERR_SYNTAX
 271
 272 /*
 273  * Return a string describing a pwmd protocol error code.
 274  */
 275 const char *pwmd_strerror(gpg_error_t error);
 276
 277 #ifdef __cplusplus
 278 }
 279 #endif
 280
 281 #endif