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 #define LIBPWMD_VERSION 0x404
  23
  24 #include <assuan.h>
  25 #include <gpg-error.h>
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /*
  32  * A handle is a pointer to a pwm_t that is returned with pwmd_connect().
  33  */
  34 struct pwm_s;
  35 typedef struct pwm_s pwm_t;
  36
  37 /*
  38  * Used with pwmd_open_nb() and pwmd_save_nb(). Both are non-blocking
  39  * functions for pin retrieval with pinentry. The pwmd_open_nb_finalize() and
  40  * pwmd_save_nb_finalize() functions use this type after a successful read()
  41  * from the returned file descriptor of those functions.
  42  */
  43 typedef struct {
  44     char filename[FILENAME_MAX];
  45     int fd;                             /* Closed after the finalize function. */
  46     gpg_error_t error;                  /* Returned from the NB function. */
  47 } pwmd_nb_status_t;
  48
  49 /*
  50  * A custom callback password retrieval function which is set with
  51  * pwmd_setopt().
  52  */
  53 typedef char *(*pwmd_password_fn)(pwm_t *pwm, void *data);
  54
  55 /*
  56  * A callback to be set with pwmd_setopt() that processes Assuan protocol
  57  * status messages. The 'line' is the status message prefixed with the
  58  * keyword.
  59  */
  60 typedef int (*pwmd_status_fn)(void *data, const char *line);
  61
  62
  63 /*
  64  * A callback to be set with pwmd_setopt() that reads data from an INQUIRE
  65  * command (i.e., STORE). 'data' is set with PWMD_OPTION_INQUIRE_DATA.
  66  * 'keyword' is the command which the INQUIRE is related (i.e., "STORE"). 'rc'
  67  * is the return code from assuan_send_data() and is initially 0 on the first
  68  * call to the set function. This gives the client a chance to cleanup and
  69  * should probably return the same error code after doing so. 'result' and
  70  * 'len' are set to the data and length to be sent without modification. The
  71  * function should return GPG_ERR_EOF when no more data needs to be sent, 0
  72  * when there is more data pending or an error code which will terminate the
  73  * INQUIRE.
  74  */
  75 typedef int (*pwmd_inquire_fn)(void *data, const char *keyword,
  76         gpg_error_t rc, char **result, size_t *len);
  77
  78 typedef enum {
  79     /*
  80      * PWMD_OPTION_PASSWORD_FUNC
  81      *
  82      * Function to retrieve a password. This function should return an
  83      * string which is the password or NULL on error.
  84      */
  85     PWMD_OPTION_PASSWORD_FUNC,
  86
  87     /*
  88      * PWMD_OPTION_PASSWORD_DATA
  89      *
  90      * Data passed to the password function.
  91      */
  92     PWMD_OPTION_PASSWORD_DATA,
  93
  94     /*
  95      * PWMD_OPTION_PINENTRY
  96      *
  97      * The following argument should be of type int and set to 1 to enable the
  98      * use of pinentry(1) to retrieve passwords. Setting to 0 will disable
  99      * using pinentry and the password must be set with PWMD_OPTION_PASSWORD
 100      * or gotten from PWMD_OPTION_PASSWORD_FUNC.
 101      */
 102     PWMD_OPTION_PINENTRY,
 103
 104     /*
 105      * PWMD_OPTION_PINENTRY_TRIES
 106      *
 107      * The number of password tries before giving up. If the pinentry "Cancel"
 108      * button is selected, pinentry will abort. Must be > 0. The default is 3.
 109      */
 110     PWMD_OPTION_PINENTRY_TRIES,
 111
 112     /*
 113      * PWMD_OPTION_PINENTRY_PATH
 114      *
 115      * The full pathname to the pinentry program. If not specified,
 116      * /usr/bin/pinentry will be used.
 117      */
 118     PWMD_OPTION_PINENTRY_PATH,
 119
 120     /*
 121      * PWMD_OPTION_PINENTRY_TTY
 122      *
 123      * pinentry --ttyname.
 124      */
 125     PWMD_OPTION_PINENTRY_TTY,
 126
 127     /*
 128      * PWMD_OPTION_PINENTRY_DISPLAY
 129      *
 130      * pinentry --display
 131      */
 132     PWMD_OPTION_PINENTRY_DISPLAY,
 133
 134     /*
 135      * PWMD_OPTION_PINENTRY_TERM
 136      *
 137      * pinentry --ttytype
 138      */
 139     PWMD_OPTION_PINENTRY_TERM,
 140
 141     /*
 142      * PWMD_OPTION_PASSWORD
 143      *
 144      * The following argument should be of type char* which specifies the
 145      * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and
 146      * PWMD_OPTION_PINENTRY is 0. The password will be kept in memory until
 147      * pwmd_close() is called so setting this option isn't needed each time
 148      * pwmd_open() or pwmd_save() is called regardless of pwmd cache settings.
 149      */
 150     PWMD_OPTION_PASSWORD,
 151
 152     /*
 153      * PWMD_OPTION_PINENTRY_TITLE
 154      * PWMD_OPTION_PINENTRY_PROMPT
 155      * PWMD_OPTION_PINENTRY_DESC
 156      *
 157      * The following argument is of type char* which specifies either the
 158      * title, prompt or description in the pinentry program when
 159      * PWMD_OPTION_PINENTRY is set.
 160      */
 161      PWMD_OPTION_PINENTRY_TITLE,
 162      PWMD_OPTION_PINENTRY_PROMPT,
 163      PWMD_OPTION_PINENTRY_DESC,
 164
 165      /*
 166       * PWMD_OPTION_STATUS_FUNC
 167       *
 168       * A function to be called when a status line is sent from pwmd. This
 169       * function should return 0 on success or a gpg-error error code. This
 170       * function won't be used when getting a password with pinentry.
 171       */
 172      PWMD_OPTION_STATUS_FUNC,
 173
 174      /*
 175       * PWMD_OPTION_STATUS_DATA
 176       *
 177       * Data passed to the status function.
 178       */
 179      PWMD_OPTION_STATUS_DATA,
 180
 181      /*
 182       * PWMD_OPTION_INQUIRE_FUNC
 183       * FIXME
 184       *
 185       * The function to retrieve data for an INQUIRE.
 186       */
 187      PWMD_OPTION_INQUIRE_FUNC,
 188
 189      /*
 190       * PWMD_OPTION_INQUIRE_DATA
 191       *
 192       * Data passed to the inquire function.
 193       */
 194      PWMD_OPTION_INQUIRE_DATA,
 195 } pwmd_option_t;
 196
 197 /*
 198  * Initialize the library. This sets up various things and must be called
 199  * before the other functions.
 200  */
 201 gpg_error_t pwmd_init(void);
 202
 203 /*
 204  * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
 205  * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
 206  * with the other functions or NULL if there was an error in which case
 207  * 'error' is set to an error code which may be described by pwmd_strerror().
 208  */
 209 pwm_t *pwmd_connect(const char *socket_path, gpg_error_t *error) __attribute__ ((warn_unused_result));
 210
 211 /*
 212  * Sets a libpwmd option 'opt'. The next argument should be of the data type
 213  * required for the option. Returns 0 on success or an error code.
 214  */
 215 gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...) __attribute__ ((warn_unused_result));
 216
 217 /*
 218  * Opens a file 'filename' (the OPEN command). The filename is not a full path
 219  * but only filename which is looked for in the pwmd configured data
 220  * directory. How the password is gotten depends on options set with
 221  * pwmd_setopt() and whether the file is cached on the server. Returns 0 on
 222  * success or an error code.
 223  */
 224 gpg_error_t pwmd_open(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result));
 225
 226 /*
 227  * This is like pwmd_open() but won't block the process when pinentry is used
 228  * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
 229  * on the server or if the file doesn't exist on the file system (a new file).
 230  * Otherwise it returns a file descriptor that select() can use. When ready
 231  * for a read, read() should read a pwmd_nb_status_t. If there is a system
 232  * error (pipe() or fork()), then -1 is returned and 'error' is set to an
 233  * error code that pwmd_strerror() can describe. See pwmd_open_nb_finalize().
 234  *
 235  * The 'timeout' parameter specifies the number of seconds until the pinentry
 236  * terminates. Setting to 0 (the default) will disable timeouts. Note that the
 237  * child process will reset the SIGALRM handler (if any) to it's own handler
 238  * and that the actual OPEN command isn't calculated as part of the elapsed
 239  * time.
 240  *
 241  * Be sure to set PWMD_OPTION_PINENTRY.
 242  */
 243 int pwmd_open_nb(pwm_t *pwm, gpg_error_t *error, const char *filename, int timeout) __attribute__ ((warn_unused_result));
 244
 245 /*
 246  * When a file descriptor has been returned from pwmd_open_nb() and after a
 247  * successful read(), you should call pwmd_open_nb_finalize() to update the
 248  * 'pwm' handle. If there was a pinentry or protocol error
 249  * pwmd_open_nb_finalize() will return an error code or 0 on success. Note
 250  * that pwmd_open_nb_finalize() will close the file descriptor returned from
 251  * pwmd_open_nb().
 252  */
 253 gpg_error_t pwmd_open_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 254
 255 /*
 256  * Sends the SAVE command to the associated handle 'pwm'. If a password is
 257  * required, how it is gotten depends on options set with pwmd_setopt().
 258  * Returns 0 on success or an error code.
 259  */
 260 gpg_error_t pwmd_save(pwm_t *pwm) __attribute__ ((warn_unused_result));
 261
 262 /*
 263  * This is like pwmd_save() but won't block the process when pinentry is used
 264  * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
 265  * on the server or if the file doesn't exist on the file system (a new file).
 266  * Otherwise it returns a file descriptor that select() can use. When ready
 267  * for a read, read() should read a pwmd_nb_status_t. If there is a system
 268  * error (pipe() or fork()), then -1 is returned and 'error' is set to an
 269  * error code that pwmd_strerror() can describe. See pwmd_save_nb_finalize().
 270  *
 271  * Note that there is no timeout setting. If a password is required, pinentry
 272  * won't timeout.
 273  *
 274  * Be sure to set PWMD_OPTION_PINENTRY.
 275  */
 276 int pwmd_save_nb(pwm_t *pwm, gpg_error_t *error) __attribute__ ((warn_unused_result));
 277
 278 /*
 279  * When a file descriptor has been returned from pwmd_save_nb() and after a
 280  * successful read(), you should call pwmd_save_nb_finalize() to update the
 281  * 'pwm' handle. If there was a pinentry or protocol error
 282  * pwmd_save_nb_finalize() will return an error code or 0 on success. Note
 283  * that pwmd_save_nb_finalize() will close the file descriptor returned from
 284  * pwmd_save_nb().
 285  */
 286 gpg_error_t pwmd_save_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 287
 288 /*
 289  * Terminates a pinentry process. If your not using pwmd_open_nb() and want to
 290  * timeout the associated pinentry process, then call this function after your
 291  * timer has expired. Returns 0 on success or an error code.
 292  */
 293 gpg_error_t pwmd_terminate_pinentry(pwm_t *pwm) __attribute__ ((warn_unused_result));
 294
 295 /*
 296  * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
 297  * command fails an error code is returned which may be described by passing
 298  * the error to pwmd_strerror(). If successful the function returns 0 and the
 299  * 'result' is the character data of the command or NULL if there was none.
 300  *
 301  * A note about the BYE command: Client's should not send this command
 302  * directly with pwmd_command(). They should use pwmd_close() instead because
 303  * libassuan will close the file descriptors with the associated context. This
 304  * is fine except when pwmd_close() is called. pwmd_close() calls
 305  * assuan_disconnect() which then sends the BYE command to the closed file
 306  * descriptor resulting in a segfault.
 307  *
 308  * For commands which use an INQUIRE, please use the inquire functions
 309  * below.
 310  */
 311 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...) __attribute__ ((warn_unused_result));
 312
 313 /*
 314  * For use with commands that use the libassuan INQUIRE protocol command
 315  * (e.g., STORE). It initializes a data connection to the server using the
 316  * inquire command 'cmd'. Returns 0 on success or an error code.
 317  *
 318  * Note that these inquire functions are less descriptive about errors other
 319  * than libassuan and you'll probably have a better error message in the pwmd
 320  * logs.
 321  */
 322 gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd);
 323
 324 /*
 325  * After calling pwmd_inquire(), call this function repeatedly until all of
 326  * your data has been sent. Returns 0 on success or an error code.
 327  */
 328 gpg_error_t pwmd_inquire_process(pwm_t *pwm, const void *buf, size_t len);
 329
 330 /*
 331  * After all data has been processed with pwmd_inquire_process(), call this
 332  * function to end the command. Returns 0 on success or an error code.
 333  */
 334 gpg_error_t pwmd_inquire_finish(pwm_t *pwm);
 335
 336 /*
 337  * Free's the memory used by the result of pwmd_command() if any. It is
 338  * important to use this function because libpwmd keeps track of all memory
 339  * de/allocations.
 340  */
 341 void pwmd_free_result(void *);
 342
 343 /*
 344  * Closes the connection to the socket and frees the resources of the handle.
 345  * Returns no value.
 346  */
 347 void pwmd_close(pwm_t *pwm);
 348
 349 /*
 350  * Protocol error codes.
 351  */
 352 #define EPWMD_KEY               GPG_ERR_WRONG_KEY_USAGE
 353 #define EPWMD_BADKEY            GPG_ERR_INV_PASSPHRASE
 354 #define EPWMD_COMMAND_SYNTAX    GPG_ERR_SYNTAX
 355 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_NOT_FOUND
 356 #define EPWMD_ACCOUNT_EXISTS    GPG_ERR_AMBIGUOUS_NAME
 357 #define EPWMD_CACHE_NOT_FOUND   GPG_ERR_NOT_FOUND
 358 #define EPWMD_ATTR_SYNTAX       GPG_ERR_SYNTAX
 359 #define EPWMD_ATTR_NOT_FOUND    GPG_ERR_NOT_FOUND
 360 #define EPWMD_INVALID_FILENAME  GPG_ERR_INV_NAME
 361 #define EPWMD_EMPTY_ELEMENT     GPG_ERR_NO_VALUE
 362 #define EPWMD_INVALID_ELEMENT   GPG_ERR_INV_VALUE
 363 #define EPWMD_ERROR             GPG_ERR_USER_1
 364 #define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
 365 #define EPWMD_LOOP              GPG_ERR_USER_3
 366 #define EPWMD_NO_FILE           GPG_ERR_USER_4
 367 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_5
 368 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_6
 369 #define EPWMD_MAX               GPG_ERR_USER_7
 370
 371 /*
 372  * Return a string describing a pwmd protocol error code.
 373  */
 374 const char *pwmd_strerror(gpg_error_t error);
 375
 376 #ifdef __cplusplus
 377 }
 378 #endif
 379
 380 #endif