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