libpwmd.h.in

   1 /* vim:tw=78:ts=8:sw=4:set ft=c:  */
   2 /*
   3     Copyright (C) 2006-2009 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  02110-1301  USA
  18 */
  19 #ifndef LIBPWMD_H
  20 #define LIBPWMD_H
  21
  22 #define LIBPWMD_VERSION 0x@VER_MAJOR@@VER_MINOR@@VER_PATCH@
  23
  24 #include <gpg-error.h>
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /*
  31  * A handle is a pointer to a pwm_t that is returned with pwmd_connect().
  32  */
  33 struct pwm_s;
  34 typedef struct pwm_s pwm_t;
  35
  36 /*
  37  * Used with pwmd_open_nb() and pwmd_save_nb(). Both are non-blocking
  38  * functions for pin retrieval with pinentry. The pwmd_open_nb_finalize() and
  39  * pwmd_save_nb_finalize() functions use this type after a successful read()
  40  * from the returned file descriptor of those functions.
  41  *
  42  * Although version 1.4 and later of pwmd has it's own support for pinentry,
  43  * commands that uses pinentry will block and as a result block the client. So
  44  * these non-blocking functions may be used to retrieve the key before sending
  45  * the command that requires a key.
  46  *
  47  * Update: You can use pwmd_open_async() and pwmd_save_async() for
  48  * non-blocking pin retrieval. These will have pwmd use it's pinentry method
  49  * rather than have libpwmd fork(). pwmd_open_nb() and pwmd_save_nb() will be
  50  * kept (both were previously flagged as deprecated) in case pin retrieval
  51  * isn't possible with pwmd.
  52  */
  53 typedef struct {
  54     char filename[FILENAME_MAX];
  55     int fd;                             /* Closed after the finalize function. */
  56     gpg_error_t error;                  /* Returned from the NB function. */
  57 } pwmd_nb_status_t;
  58
  59 /*
  60  * For use with pwmd_process(). pwmd_open_async() and pwmd_save_async() use
  61  * this data type.
  62  */
  63 typedef enum {
  64     ASYNC_INIT,
  65     ASYNC_PROCESS,
  66     ASYNC_DONE,
  67 } pwmd_async_t;
  68
  69 /*
  70  * A custom callback password retrieval function which is set with
  71  * pwmd_setopt(). This has priority over other retrieval methods if set.
  72  */
  73 typedef char *(*pwmd_password_fn)(pwm_t *pwm, void *data);
  74
  75 /*
  76  * A callback to be set with pwmd_setopt() that processes Assuan protocol
  77  * status messages. The 'line' is the status message which is prefixed with
  78  * the status keyword.
  79  */
  80 typedef int (*pwmd_status_fn)(void *data, const char *line);
  81
  82 /*
  83  * A callback function that is passed to pwmd_inquire(). 'data' is the user
  84  * data that was passed to pwmd_inquire(). 'keyword' is the same as the 'cmd'
  85  * argument to pwmd_inquire().
  86  *
  87  * 'rc' is the return code from assuan_send_data() and is initially 0 on the
  88  * first call to the set callback. This gives the client a chance to cleanup
  89  * if assuan_send_data() fails for some reason and should probably return the
  90  * same error code, if set, after doing so.
  91  *
  92  * 'result' should be set to the data to be sent which is of 'len' bytes. The
  93  * data is not modified.
  94  *
  95  * The function should return GPG_ERR_EOF when no more data needs to be sent
  96  * or to finish sending the set 'result' and end the INQUIRE, 0 if there is
  97  * more data pending or an error code which will terminate the INQUIRE.
  98  */
  99 typedef gpg_error_t (*pwmd_inquire_fn)(void *data, const char *keyword,
 100         gpg_error_t rc, char **result, size_t *len);
 101
 102 /*
 103  * Library options which are set with pwmd_setopt().
 104  */
 105 typedef enum {
 106     /*
 107      * PWMD_OPTION_PASSWORD_FUNC
 108      *
 109      * Function to retrieve a password. This function should return an
 110      * string which is the password or NULL on error.
 111      */
 112     PWMD_OPTION_PASSWORD_FUNC,
 113
 114     /*
 115      * PWMD_OPTION_PASSWORD_DATA
 116      *
 117      * Data passed to the password function.
 118      */
 119     PWMD_OPTION_PASSWORD_DATA,
 120
 121     /*
 122      * PWMD_OPTION_PINENTRY
 123      *
 124      * The following argument should be of type int and set to 1 to enable the
 125      * use of pinentry(1) to retrieve passwords. Setting to 0 will disable
 126      * using pinentry and the password must be set with PWMD_OPTION_PASSWORD
 127      * or gotten from PWMD_OPTION_PASSWORD_FUNC. The pwmd command "OPTION
 128      * PINENTRY=0" is sent when this option is set (1) to prevent pinentry
 129      * from being called on the pwmd server and enabled when unset.
 130      */
 131     PWMD_OPTION_PINENTRY,
 132
 133     /*
 134      * PWMD_OPTION_PINENTRY_TRIES
 135      *
 136      * The number of password tries before giving up. If the pinentry "Cancel"
 137      * button is selected, pinentry will abort. Must be > 0. The default is 3.
 138      */
 139     PWMD_OPTION_PINENTRY_TRIES,
 140
 141     /*
 142      * PWMD_OPTION_PINENTRY_PATH
 143      *
 144      * The full pathname to the pinentry program. If not specified,
 145      * /usr/bin/pinentry will be used.
 146      */
 147     PWMD_OPTION_PINENTRY_PATH,
 148
 149     /*
 150      * PWMD_OPTION_PINENTRY_TTY
 151      *
 152      * pinentry --ttyname.
 153      */
 154     PWMD_OPTION_PINENTRY_TTY,
 155
 156     /*
 157      * PWMD_OPTION_PINENTRY_DISPLAY
 158      *
 159      * pinentry --display
 160      */
 161     PWMD_OPTION_PINENTRY_DISPLAY,
 162
 163     /*
 164      * PWMD_OPTION_PINENTRY_TERM
 165      *
 166      * pinentry --ttytype
 167      */
 168     PWMD_OPTION_PINENTRY_TERM,
 169
 170     /*
 171      * PWMD_OPTION_PASSWORD
 172      *
 173      * The following argument should be of type char* which specifies the
 174      * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and
 175      * PWMD_OPTION_PINENTRY is 0. The password will be kept in memory until
 176      * pwmd_close() is called so setting this option isn't needed each time
 177      * pwmd_open() or pwmd_save() is called regardless of pwmd cache settings.
 178      */
 179     PWMD_OPTION_PASSWORD,
 180
 181     /*
 182      * PWMD_OPTION_PINENTRY_TITLE
 183      * PWMD_OPTION_PINENTRY_PROMPT
 184      * PWMD_OPTION_PINENTRY_DESC
 185      *
 186      * The following argument is of type char* which specifies either the
 187      * title, prompt or description in the pinentry program when
 188      * PWMD_OPTION_PINENTRY is set. Note that any CR, LF or % must be percent
 189      * escape (the hexidecimal value of the character).
 190      */
 191      PWMD_OPTION_PINENTRY_TITLE,
 192      PWMD_OPTION_PINENTRY_PROMPT,
 193      PWMD_OPTION_PINENTRY_DESC,
 194
 195      /* Internationalization: --lc-ctype and --lc-messages options to
 196       * pinentry. */
 197      PWMD_OPTION_PINENTRY_LC_CTYPE,
 198      PWMD_OPTION_PINENTRY_LC_MESSAGES,
 199
 200      /* PWMD_OPTION_PINENTRY_TIMEOUT
 201       *
 202       * "OPTION TIMEOUT" pwmd command. Only useful when pwmd is used as the
 203       * pinentry method.
 204       */
 205      PWMD_OPTION_PINENTRY_TIMEOUT,
 206
 207      /*
 208       * PWMD_OPTION_STATUS_FUNC
 209       *
 210       * A function to be called when a status line is sent from pwmd. This
 211       * function should return 0 on success or a gpg-error error code. This
 212       * function won't be used when getting a password with pinentry.
 213       */
 214      PWMD_OPTION_STATUS_FUNC,
 215
 216      /*
 217       * PWMD_OPTION_STATUS_DATA
 218       *
 219       * Data passed to the status function.
 220       */
 221      PWMD_OPTION_STATUS_DATA,
 222 } pwmd_option_t;
 223
 224 /*
 225  * Initialize the library. This sets up various things and must be called
 226  * before the other functions.
 227  */
 228 gpg_error_t pwmd_init(void);
 229
 230 /*
 231  * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
 232  * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
 233  * with the other functions or NULL if there was an error in which case
 234  * 'error' is set to an error code which may be described by pwmd_strerror().
 235  */
 236 pwm_t *pwmd_connect(const char *socket_path, gpg_error_t *error) __attribute__ ((warn_unused_result));
 237
 238 /*
 239  * Sets 'ctx' to the assuan context associated with the handle 'pwm' and 'fd'
 240  * to the socket file descriptor. Returns 0 on success or an error code.
 241  *
 242  * Note than ctx is really an assuan_context_t *.
 243  */
 244 gpg_error_t pwmd_assuan_ctx(pwm_t *pwm, void *ctx, int *fd) __attribute__ ((warn_unused_result));
 245
 246 /*
 247  * A wrapper around assuan_pending_line() and assuan_read_line(). Returns 0 if
 248  * there was a pending line and sets 'line' to the content and 'len' to the
 249  * length. Returns GPG_ERR_NO_DATA if there was no pending line. Otherwise the
 250  * error returned from assuan_read_line() is returned.
 251  */
 252 gpg_error_t pwmd_pending_line(pwm_t *pwm, char **line, size_t *len) __attribute__ ((warn_unused_result));
 253
 254 /*
 255  * Sets a libpwmd option 'opt'. The next argument should be of the data type
 256  * required for the option. Returns 0 on success or an error code.
 257  */
 258 gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...) __attribute__ ((warn_unused_result));
 259
 260 /*
 261  * Opens a file 'filename' (the OPEN command). The filename is not a full path
 262  * but only filename which is looked for in the pwmd configured data
 263  * directory. How the password is gotten depends on the options set with
 264  * pwmd_setopt() and whether the file is cached on the server. Returns 0 on
 265  * success or an error code.
 266  */
 267 gpg_error_t pwmd_open(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result));
 268
 269 /*
 270  * This is like pwmd_open() but won't block the process when pinentry is used
 271  * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
 272  * on the server or if the file doesn't exist on the file system (a new file).
 273  * Otherwise it returns a file descriptor that select() can use. When ready
 274  * for a read, read() should read a pwmd_nb_status_t. If there is a system
 275  * error (pipe() or fork()), then -1 is returned and 'error' is set to an
 276  * error code that pwmd_strerror() can describe. See pwmd_open_nb_finalize().
 277  *
 278  * The 'timeout' parameter specifies the number of seconds until the pinentry
 279  * terminates. Setting to 0 (the default) will disable timeouts. Note that the
 280  * child process will reset the SIGALRM handler (if any) to it's own handler
 281  * and that the actual OPEN command isn't calculated as part of the elapsed
 282  * time.
 283  *
 284  * Be sure to set PWMD_OPTION_PINENTRY.
 285  */
 286 int pwmd_open_nb(pwm_t *pwm, gpg_error_t *error, const char *filename,
 287         int timeout) __attribute__ ((warn_unused_result));
 288
 289 /*
 290  * When a file descriptor has been returned from pwmd_open_nb() and after a
 291  * successful read(), you should call pwmd_open_nb_finalize() to update the
 292  * 'pwm' handle. If there was a pinentry or protocol error
 293  * pwmd_open_nb_finalize() will return an error code or 0 on success. Note
 294  * that pwmd_open_nb_finalize() will close the file descriptor returned from
 295  * pwmd_open_nb().
 296  */
 297 gpg_error_t pwmd_open_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 298
 299 /*
 300  * This is the preferred way to do a non-blocking open. The difference from
 301  * pwmd_open_nb() is that libpwmd wont fork() to get the pin. Instead, it will
 302  * let pwmd use it's pinentry retrieval method. When successful this function
 303  * returns 0 and pwmd_process() should be called until the command completes.
 304  *
 305  * If pwmd is unable to use pinentry, and non-blocking is needed, then
 306  * pwmd_open_nb() can be used instead.
 307  */
 308 gpg_error_t pwmd_open_async(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result));
 309 ;
 310
 311 /*
 312  * After pwmd_open_async() or pwmd_save_async() returns 0, this function
 313  * should be called until ASYNC_DONE is returned. It will return ASYNC_PROCESS
 314  * when the command is still running. After ASYNC_DONE is returned, any error
 315  * that may have occurred is stored in 'rc'. If an error occurred or not,
 316  * pwmd_finalize() must be called to reset a control variable so the next
 317  * async command may be performed.
 318  */
 319 pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc) __attribute__ ((warn_unused_result));
 320 ;
 321
 322 /*
 323  * Resets the control variable for the associated handle. Call this function
 324  * after ASYNC_DONE is returned from pwmd_process().
 325  */
 326 gpg_error_t pwmd_finalize(pwm_t *pwm) __attribute__ ((warn_unused_result));
 327 ;
 328
 329 /*
 330  * Sends the SAVE command to the associated handle 'pwm'. If a password is
 331  * required, how it is gotten depends on options set with pwmd_setopt().
 332  * Returns 0 on success or an error code.
 333  */
 334 gpg_error_t pwmd_save(pwm_t *pwm) __attribute__ ((warn_unused_result));
 335
 336 /*
 337  * This is like pwmd_save() but won't block the process when pinentry is used
 338  * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
 339  * on the server or if the file doesn't exist on the file system (a new file).
 340  * Otherwise it returns a file descriptor that select() can use. When ready
 341  * for a read, read() should read a pwmd_nb_status_t. If there is a system
 342  * error (pipe() or fork()), then -1 is returned and 'error' is set to an
 343  * error code that pwmd_strerror() can describe. See pwmd_save_nb_finalize().
 344  *
 345  * Note that there is no timeout setting. If a password is required, pinentry
 346  * won't timeout but will wait until either it is canceled or a successful
 347  * passphrase is entered.
 348  *
 349  * Be sure to set PWMD_OPTION_PINENTRY.
 350  */
 351 int pwmd_save_nb(pwm_t *pwm, gpg_error_t *error) __attribute__ ((warn_unused_result));
 352
 353 /*
 354  * When a file descriptor has been returned from pwmd_save_nb() and after a
 355  * successful read(), you should call pwmd_save_nb_finalize() to update the
 356  * 'pwm' handle. If there was a pinentry or protocol error
 357  * pwmd_save_nb_finalize() will return an error code or 0 on success. Note
 358  * that pwmd_save_nb_finalize() will close the file descriptor returned from
 359  * pwmd_save_nb().
 360  */
 361 gpg_error_t pwmd_save_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 362
 363 /*
 364  * Like pwmd_save_nb() but uses pwmd to launch pinentry rather than having
 365  * libpwmd fork(). This function returns 0 on success and pwmd_process()
 366  * should be called until the command completes.
 367  */
 368 gpg_error_t pwmd_save_async(pwm_t *pwm) __attribute__ ((warn_unused_result));
 369 ;
 370
 371 /*
 372  * Terminates a pinentry process. If your not using pwmd_open_nb() and want to
 373  * timeout the associated pinentry process, then call this function after your
 374  * timer has expired. Returns 0 on success or an error code.
 375  */
 376 gpg_error_t pwmd_terminate_pinentry(pwm_t *pwm) __attribute__ ((warn_unused_result));
 377
 378 /*
 379  * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
 380  * command fails an error code is returned which may be described by passing
 381  * the error to pwmd_strerror(). If successful the function returns 0 and the
 382  * 'result' is the character data of the command or NULL if there was none.
 383  *
 384  * For commands which use an INQUIRE (i.e., STORE), use pwmd_inquire() and not
 385  * pwmd_command().
 386  *
 387  * A note about the BYE command: Client's should not send this command
 388  * directly with pwmd_command(). They should use pwmd_close() instead because
 389  * libassuan will close the file descriptors with the associated context.
 390  */
 391 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...) __attribute__ ((warn_unused_result));
 392 gpg_error_t pwmd_command_ap(pwm_t *pwm, char **result, const char *cmd,
 393         va_list ap) __attribute__ ((warn_unused_result));
 394
 395 /*
 396  * Commands which use an INQUIRE to send data (i.e., STORE) should use this
 397  * function and not pwmd_command(). 'cmd' is the command to send and is also
 398  * the 'keyword' argument passed to the callback function 'func'. 'data' is
 399  * user data passed to the callback function. Returns 0 on success or an
 400  * error code which may have been returned from the callback function.
 401  */
 402 gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd, pwmd_inquire_fn func,
 403         void *data) __attribute__ ((warn_unused_result));
 404
 405 /*
 406  * Free the memory used by the result of pwmd_command() if any. It is
 407  * important to use this function because libpwmd keeps track of all memory
 408  * de/allocations.
 409  */
 410 void pwmd_free_result(void *);
 411
 412 /*
 413  * Closes the connection to the socket and frees the resources of the handle.
 414  * Returns no value.
 415  */
 416 void pwmd_close(pwm_t *pwm);
 417
 418 /*
 419  * Protocol error codes.
 420  */
 421 #define EPWMD_BADKEY            GPG_ERR_INV_PASSPHRASE
 422 #define EPWMD_COMMAND_SYNTAX    GPG_ERR_SYNTAX
 423 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_ELEMENT_NOT_FOUND
 424 #define EPWMD_ACCOUNT_EXISTS    GPG_ERR_AMBIGUOUS_NAME
 425 #define EPWMD_CACHE_NOT_FOUND   GPG_ERR_NOT_FOUND
 426 #define EPWMD_ATTR_SYNTAX       GPG_ERR_SYNTAX
 427 #define EPWMD_ATTR_NOT_FOUND    GPG_ERR_NOT_FOUND
 428 #define EPWMD_INVALID_FILENAME  GPG_ERR_INV_VALUE
 429 #define EPWMD_EMPTY_ELEMENT     GPG_ERR_NO_VALUE
 430 #define EPWMD_INVALID_ELEMENT   GPG_ERR_INV_VALUE
 431 #define EPWMD_ERROR             GPG_ERR_USER_1
 432 #define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
 433 #define EPWMD_LOOP              GPG_ERR_USER_3
 434 #define EPWMD_NO_FILE           GPG_ERR_USER_4
 435 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_5
 436 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_6
 437 #define EPWMD_MAX               GPG_ERR_USER_7
 438
 439 /*
 440  * Return a string describing a pwmd protocol error code.
 441  */
 442 const char *pwmd_strerror(gpg_error_t error);
 443
 444 #ifdef __cplusplus
 445 }
 446 #endif
 447
 448 #endif