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      /*
 196       * PWMD_OPTION_STATUS_FUNC
 197       *
 198       * A function to be called when a status line is sent from pwmd. This
 199       * function should return 0 on success or a gpg-error error code. This
 200       * function won't be used when getting a password with pinentry.
 201       */
 202      PWMD_OPTION_STATUS_FUNC,
 203
 204      /*
 205       * PWMD_OPTION_STATUS_DATA
 206       *
 207       * Data passed to the status function.
 208       */
 209      PWMD_OPTION_STATUS_DATA,
 210 } pwmd_option_t;
 211
 212 /*
 213  * Initialize the library. This sets up various things and must be called
 214  * before the other functions.
 215  */
 216 gpg_error_t pwmd_init(void);
 217
 218 /*
 219  * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
 220  * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
 221  * with the other functions or NULL if there was an error in which case
 222  * 'error' is set to an error code which may be described by pwmd_strerror().
 223  */
 224 pwm_t *pwmd_connect(const char *socket_path, gpg_error_t *error) __attribute__ ((warn_unused_result));
 225
 226 /*
 227  * Sets 'ctx' to the assuan context associated with the handle 'pwm' and 'fd'
 228  * to the socket file descriptor. Returns 0 on success or an error code.
 229  *
 230  * Note than ctx is really an assuan_context_t *.
 231  */
 232 gpg_error_t pwmd_assuan_ctx(pwm_t *pwm, void *ctx, int *fd) __attribute__ ((warn_unused_result));
 233
 234 /*
 235  * A wrapper around assuan_pending_line() and assuan_read_line(). Returns 0 if
 236  * there was a pending line and sets 'line' to the content and 'len' to the
 237  * length. Returns GPG_ERR_NO_DATA if there was no pending line. Otherwise the
 238  * error returned from assuan_read_line() is returned.
 239  */
 240 gpg_error_t pwmd_pending_line(pwm_t *pwm, char **line, size_t *len) __attribute__ ((warn_unused_result));
 241
 242 /*
 243  * Sets a libpwmd option 'opt'. The next argument should be of the data type
 244  * required for the option. Returns 0 on success or an error code.
 245  */
 246 gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...) __attribute__ ((warn_unused_result));
 247
 248 /*
 249  * Opens a file 'filename' (the OPEN command). The filename is not a full path
 250  * but only filename which is looked for in the pwmd configured data
 251  * directory. How the password is gotten depends on the options set with
 252  * pwmd_setopt() and whether the file is cached on the server. Returns 0 on
 253  * success or an error code.
 254  */
 255 gpg_error_t pwmd_open(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result));
 256
 257 /*
 258  * This is like pwmd_open() but won't block the process when pinentry is used
 259  * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
 260  * on the server or if the file doesn't exist on the file system (a new file).
 261  * Otherwise it returns a file descriptor that select() can use. When ready
 262  * for a read, read() should read a pwmd_nb_status_t. If there is a system
 263  * error (pipe() or fork()), then -1 is returned and 'error' is set to an
 264  * error code that pwmd_strerror() can describe. See pwmd_open_nb_finalize().
 265  *
 266  * The 'timeout' parameter specifies the number of seconds until the pinentry
 267  * terminates. Setting to 0 (the default) will disable timeouts. Note that the
 268  * child process will reset the SIGALRM handler (if any) to it's own handler
 269  * and that the actual OPEN command isn't calculated as part of the elapsed
 270  * time.
 271  *
 272  * Be sure to set PWMD_OPTION_PINENTRY.
 273  */
 274 int pwmd_open_nb(pwm_t *pwm, gpg_error_t *error, const char *filename,
 275         int timeout) __attribute__ ((warn_unused_result));
 276
 277 /*
 278  * When a file descriptor has been returned from pwmd_open_nb() and after a
 279  * successful read(), you should call pwmd_open_nb_finalize() to update the
 280  * 'pwm' handle. If there was a pinentry or protocol error
 281  * pwmd_open_nb_finalize() will return an error code or 0 on success. Note
 282  * that pwmd_open_nb_finalize() will close the file descriptor returned from
 283  * pwmd_open_nb().
 284  */
 285 gpg_error_t pwmd_open_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 286
 287 /*
 288  * This is the preferred way to do a non-blocking open. The difference from
 289  * pwmd_open_nb() is that libpwmd wont fork() to get the pin. Instead, it will
 290  * let pwmd use it's pinentry retrieval method. When successful this function
 291  * returns 0 and pwmd_process() should be called until the command completes.
 292  *
 293  * If pwmd is unable to use pinentry, and non-blocking is needed, then
 294  * pwmd_open_nb() can be used instead.
 295  */
 296 gpg_error_t pwmd_open_async(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result));
 297 ;
 298
 299 /*
 300  * After pwmd_open_async() or pwmd_save_async() returns 0, this function
 301  * should be called until ASYNC_DONE is returned. It will return ASYNC_PROCESS
 302  * when the command is still running. After ASYNC_DONE is returned, any error
 303  * that may have occurred is stored in 'rc'. If an error occurred or not,
 304  * pwmd_finalize() must be called to reset a control variable so the next
 305  * async command may be performed.
 306  */
 307 pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc) __attribute__ ((warn_unused_result));
 308 ;
 309
 310 /*
 311  * Resets the control variable for the associated handle. Call this function
 312  * after ASYNC_DONE is returned from pwmd_process().
 313  */
 314 gpg_error_t pwmd_finalize(pwm_t *pwm) __attribute__ ((warn_unused_result));
 315 ;
 316
 317 /*
 318  * Sends the SAVE command to the associated handle 'pwm'. If a password is
 319  * required, how it is gotten depends on options set with pwmd_setopt().
 320  * Returns 0 on success or an error code.
 321  */
 322 gpg_error_t pwmd_save(pwm_t *pwm) __attribute__ ((warn_unused_result));
 323
 324 /*
 325  * This is like pwmd_save() but won't block the process when pinentry is used
 326  * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
 327  * on the server or if the file doesn't exist on the file system (a new file).
 328  * Otherwise it returns a file descriptor that select() can use. When ready
 329  * for a read, read() should read a pwmd_nb_status_t. If there is a system
 330  * error (pipe() or fork()), then -1 is returned and 'error' is set to an
 331  * error code that pwmd_strerror() can describe. See pwmd_save_nb_finalize().
 332  *
 333  * Note that there is no timeout setting. If a password is required, pinentry
 334  * won't timeout but will wait until either it is canceled or a successful
 335  * passphrase is entered.
 336  *
 337  * Be sure to set PWMD_OPTION_PINENTRY.
 338  */
 339 int pwmd_save_nb(pwm_t *pwm, gpg_error_t *error) __attribute__ ((warn_unused_result));
 340
 341 /*
 342  * When a file descriptor has been returned from pwmd_save_nb() and after a
 343  * successful read(), you should call pwmd_save_nb_finalize() to update the
 344  * 'pwm' handle. If there was a pinentry or protocol error
 345  * pwmd_save_nb_finalize() will return an error code or 0 on success. Note
 346  * that pwmd_save_nb_finalize() will close the file descriptor returned from
 347  * pwmd_save_nb().
 348  */
 349 gpg_error_t pwmd_save_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 350
 351 /*
 352  * Like pwmd_save_nb() but uses pwmd to launch pinentry rather than having
 353  * libpwmd fork(). This function returns 0 on success and pwmd_process()
 354  * should be called until the command completes.
 355  */
 356 gpg_error_t pwmd_save_async(pwm_t *pwm) __attribute__ ((warn_unused_result));
 357 ;
 358
 359 /*
 360  * Terminates a pinentry process. If your not using pwmd_open_nb() and want to
 361  * timeout the associated pinentry process, then call this function after your
 362  * timer has expired. Returns 0 on success or an error code.
 363  */
 364 gpg_error_t pwmd_terminate_pinentry(pwm_t *pwm) __attribute__ ((warn_unused_result));
 365
 366 /*
 367  * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
 368  * command fails an error code is returned which may be described by passing
 369  * the error to pwmd_strerror(). If successful the function returns 0 and the
 370  * 'result' is the character data of the command or NULL if there was none.
 371  *
 372  * For commands which use an INQUIRE (i.e., STORE), use pwmd_inquire() and not
 373  * pwmd_command().
 374  *
 375  * A note about the BYE command: Client's should not send this command
 376  * directly with pwmd_command(). They should use pwmd_close() instead because
 377  * libassuan will close the file descriptors with the associated context.
 378  */
 379 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...) __attribute__ ((warn_unused_result));
 380 gpg_error_t pwmd_command_ap(pwm_t *pwm, char **result, const char *cmd,
 381         va_list ap) __attribute__ ((warn_unused_result));
 382
 383 /*
 384  * Commands which use an INQUIRE to send data (i.e., STORE) should use this
 385  * function and not pwmd_command(). 'cmd' is the command to send and is also
 386  * the 'keyword' argument passed to the callback function 'func'. 'data' is
 387  * user data passed to the callback function. Returns 0 on success or an
 388  * error code which may have been returned from the callback function.
 389  */
 390 gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd, pwmd_inquire_fn func,
 391         void *data) __attribute__ ((warn_unused_result));
 392
 393 /*
 394  * Free the memory used by the result of pwmd_command() if any. It is
 395  * important to use this function because libpwmd keeps track of all memory
 396  * de/allocations.
 397  */
 398 void pwmd_free_result(void *);
 399
 400 /*
 401  * Closes the connection to the socket and frees the resources of the handle.
 402  * Returns no value.
 403  */
 404 void pwmd_close(pwm_t *pwm);
 405
 406 /*
 407  * Protocol error codes.
 408  */
 409 #define EPWMD_BADKEY            GPG_ERR_INV_PASSPHRASE
 410 #define EPWMD_COMMAND_SYNTAX    GPG_ERR_SYNTAX
 411 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_ELEMENT_NOT_FOUND
 412 #define EPWMD_ACCOUNT_EXISTS    GPG_ERR_AMBIGUOUS_NAME
 413 #define EPWMD_CACHE_NOT_FOUND   GPG_ERR_NOT_FOUND
 414 #define EPWMD_ATTR_SYNTAX       GPG_ERR_SYNTAX
 415 #define EPWMD_ATTR_NOT_FOUND    GPG_ERR_NOT_FOUND
 416 #define EPWMD_INVALID_FILENAME  GPG_ERR_INV_VALUE
 417 #define EPWMD_EMPTY_ELEMENT     GPG_ERR_NO_VALUE
 418 #define EPWMD_INVALID_ELEMENT   GPG_ERR_INV_VALUE
 419 #define EPWMD_ERROR             GPG_ERR_USER_1
 420 #define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
 421 #define EPWMD_LOOP              GPG_ERR_USER_3
 422 #define EPWMD_NO_FILE           GPG_ERR_USER_4
 423 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_5
 424 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_6
 425 #define EPWMD_MAX               GPG_ERR_USER_7
 426
 427 /*
 428  * Return a string describing a pwmd protocol error code.
 429  */
 430 const char *pwmd_strerror(gpg_error_t error);
 431
 432 #ifdef __cplusplus
 433 }
 434 #endif
 435
 436 #endif