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