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
  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  * Connects to the remote host "host". Both Ipv4 and IPv6 addresses are
 240  * supported. The "port" parameter may be -1 which uses the default pwmd
 241  * port (6466).
 242  *
 243  * The "cert" and "key" parameters should be the location of the client
 244  * certificate and client certificate key files to use during authentication.
 245  * If NULL, then the defaults ~/.pwmd/client-cert.pem and
 246  * ~/.pwmd/client-key.pem will be used. The "ca" parameter is the certificate
 247  * authority that the server certificate was signed with. If NULL, the default
 248  * ~/.pwmd/ca-cert.pem will be used.
 249  *
 250  * The "verify" parameter, when 1, will verify the hostname in the peer
 251  * certificate. The "cipher" parameter specifies the cipher suite to use for
 252  * the session.
 253  *
 254  * Returns a new handle for use with the other functions or NULL if there was
 255  * an error in which case 'error' is set to an error code which may be
 256  * described by pwmd_strerror().
 257  */
 258 pwm_t *pwmd_tcp_connect(const char *hostname, int port, const char *identity, const char *user, const char *known_hosts, gpg_error_t *error)__attribute__ ((warn_unused_result));
 259
 260 /* Like pwmd_tcp_connect() but this function wont block while doing DNS
 261  * lookups and connecting. You should call pwmd_process() only when this
 262  * function succeeds (see pwmd_process() for more information).
 263  */
 264 pwm_t *pwmd_tcp_connect_async(const char *hostname, int port, const char *identity, const char *user, const char *known_hosts, gpg_error_t *error) __attribute__ ((warn_unused_result));
 265
 266 /* Retrieve the SSH server SHA1 host key. The result must be freed with
 267  * pwmd_free_result().
 268  */
 269 char *pwmd_get_hostkey(const char *hostname, int port, gpg_error_t *rc) __attribute__ ((warn_unused_result));
 270 pwm_t *pwmd_get_hostkey_async(const char *hostname, int port, gpg_error_t *rc) __attribute__ ((warn_unused_result));
 271
 272 /*
 273  * Sets 'ctx' to the assuan context associated with the handle 'pwm' and 'fd'
 274  * to the socket file descriptor. Returns 0 on success or an error code.
 275  *
 276  * Note than ctx is really an assuan_context_t *.
 277  */
 278 gpg_error_t pwmd_assuan_ctx(pwm_t *pwm, void *ctx, int *fd) __attribute__ ((warn_unused_result));
 279
 280 /*
 281  * A wrapper around assuan_pending_line() and assuan_read_line(). Returns 0 if
 282  * there was a pending line and sets 'line' to the content and 'len' to the
 283  * length. Returns GPG_ERR_NO_DATA if there was no pending line. Otherwise the
 284  * error returned from assuan_read_line() is returned.
 285  */
 286 gpg_error_t pwmd_pending_line(pwm_t *pwm, char **line, size_t *len) __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 pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc) __attribute__ ((warn_unused_result));
 355 gpg_error_t pwmd_get_result(pwm_t *pwm, const char **result) __attribute__ ((warn_unused_result));
 356 ;
 357
 358 /*
 359  * Resets the control variable for the associated handle. Call this function
 360  * after ASYNC_DONE is returned from pwmd_process(). The return value is not
 361  * associated with the command that was being processed with pwmd_process().
 362  * This function returns 0 on success or an error if "pwm" is not a valid
 363  * handle or in an inconsistant state.
 364  *
 365  * NOTE: In the case that pwmd_tcp_connect_async() was used for the
 366  * asynchronous command and an error occurred while connecting, this function
 367  * will deallocate the resources used by the handle. You may then retry the
 368  * connection.
 369  */
 370 //FIXME merge pwmd_get_result() into this function.
 371 gpg_error_t pwmd_finalize(pwm_t *pwm) __attribute__ ((warn_unused_result));
 372 ;
 373
 374 /*
 375  * Sends the SAVE command to the associated handle 'pwm'. If a password is
 376  * required, how it is gotten depends on options set with pwmd_setopt().
 377  * Returns 0 on success or an error code.
 378  */
 379 gpg_error_t pwmd_save(pwm_t *pwm) __attribute__ ((warn_unused_result));
 380
 381 /*
 382  * This is like pwmd_save() but won't block the process when pinentry is used
 383  * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
 384  * on the server or if the file doesn't exist on the file system (a new file).
 385  * Otherwise it returns a file descriptor that select() can use. When ready
 386  * for a read, read() should read a pwmd_nb_status_t. If there is a system
 387  * error (pipe() or fork()), then -1 is returned and 'error' is set to an
 388  * error code that pwmd_strerror() can describe. See pwmd_save_nb_finalize().
 389  *
 390  * Note that there is no timeout setting. If a password is required, pinentry
 391  * won't timeout but will wait until either it is canceled or a successful
 392  * passphrase is entered.
 393  *
 394  * Be sure to set PWMD_OPTION_PINENTRY.
 395  */
 396 int pwmd_save_nb(pwm_t *pwm, gpg_error_t *error) __attribute__ ((warn_unused_result));
 397
 398 /*
 399  * When a file descriptor has been returned from pwmd_save_nb() and after a
 400  * successful read(), you should call pwmd_save_nb_finalize() to update the
 401  * 'pwm' handle. If there was a pinentry or protocol error
 402  * pwmd_save_nb_finalize() will return an error code or 0 on success. Note
 403  * that pwmd_save_nb_finalize() will close the file descriptor returned from
 404  * pwmd_save_nb().
 405  */
 406 gpg_error_t pwmd_save_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 407
 408 /*
 409  * Like pwmd_save_nb() but uses pwmd to launch pinentry rather than having
 410  * libpwmd fork(). This function returns 0 on success and pwmd_process()
 411  * should be called until the command completes.
 412  */
 413 gpg_error_t pwmd_save_async(pwm_t *pwm) __attribute__ ((warn_unused_result));
 414 ;
 415
 416 /*
 417  * Terminates a pinentry process. If your not using pwmd_open_nb() and want to
 418  * timeout the associated pinentry process, then call this function after your
 419  * timer has expired. Returns 0 on success or an error code.
 420  */
 421 gpg_error_t pwmd_terminate_pinentry(pwm_t *pwm) __attribute__ ((warn_unused_result));
 422
 423 /*
 424  * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
 425  * command fails an error code is returned which may be described by passing
 426  * the error to pwmd_strerror(). If successful the function returns 0 and the
 427  * 'result' is the character data of the command or NULL if there was none.
 428  *
 429  * For commands which use an INQUIRE (i.e., STORE), use pwmd_inquire() and not
 430  * pwmd_command().
 431  *
 432  * A note about the BYE command: Client's should not send this command
 433  * directly with pwmd_command(). They should use pwmd_close() instead because
 434  * libassuan will close the file descriptors with the associated context.
 435  */
 436 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...) __attribute__ ((warn_unused_result));
 437 gpg_error_t pwmd_command_ap(pwm_t *pwm, char **result, const char *cmd,
 438         va_list ap) __attribute__ ((warn_unused_result));
 439
 440 /*
 441  * Commands which use an INQUIRE to send data (i.e., STORE) should use this
 442  * function and not pwmd_command(). 'cmd' is the command to send and is also
 443  * the 'keyword' argument passed to the callback function 'func'. 'data' is
 444  * user data passed to the callback function. Returns 0 on success or an
 445  * error code which may have been returned from the callback function.
 446  */
 447 gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd, pwmd_inquire_fn func,
 448         void *data) __attribute__ ((warn_unused_result));
 449
 450 /*
 451  * Free the memory used by the result of pwmd_command() if any. It is
 452  * important to use this function because libpwmd keeps track of all memory
 453  * de/allocations.
 454  */
 455 void pwmd_free_result(void *);
 456
 457 /*
 458  * Closes the connection to the socket and frees the resources of the handle.
 459  * Returns no value.
 460  */
 461 void pwmd_close(pwm_t *pwm);
 462
 463 /*
 464  * Protocol error codes.
 465  */
 466 #define EPWMD_BADKEY            GPG_ERR_INV_PASSPHRASE
 467 #define EPWMD_COMMAND_SYNTAX    GPG_ERR_SYNTAX
 468 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_ELEMENT_NOT_FOUND
 469 #define EPWMD_ACCOUNT_EXISTS    GPG_ERR_AMBIGUOUS_NAME
 470 #define EPWMD_CACHE_NOT_FOUND   GPG_ERR_NOT_FOUND
 471 #define EPWMD_ATTR_SYNTAX       GPG_ERR_SYNTAX
 472 #define EPWMD_ATTR_NOT_FOUND    GPG_ERR_NOT_FOUND
 473 #define EPWMD_INVALID_FILENAME  GPG_ERR_INV_VALUE
 474 #define EPWMD_EMPTY_ELEMENT     GPG_ERR_NO_VALUE
 475 #define EPWMD_INVALID_ELEMENT   GPG_ERR_INV_VALUE
 476 #define EPWMD_ERROR             GPG_ERR_USER_1
 477 #define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
 478 #define EPWMD_LOOP              GPG_ERR_USER_3
 479 #define EPWMD_NO_FILE           GPG_ERR_USER_4
 480 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_5
 481 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_6
 482 #define EPWMD_FILE_ACCESS       GPG_ERR_USER_7
 483 #define EPWMD_MAX               GPG_ERR_USER_8
 484
 485 /*
 486  * Return a string describing a pwmd protocol error code.
 487  */
 488 const char *pwmd_strerror(gpg_error_t error);
 489
 490 #ifdef __cplusplus
 491 }
 492 #endif
 493
 494 #endif