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