libpwmd.h

   1 /* vim:tw=78:ts=8:sw=4:set ft=c:  */
   2 /*
   3     Copyright (C) 2006-2007 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  02111-1307  USA
  18 */
  19 #ifndef LIBPWMD_H
  20 #define LIBPWMD_H
  21
  22 #define LIBPWMD_VERSION 0x404
  23
  24 #include <assuan.h>
  25 #include <gpg-error.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 typedef struct {
  44     char filename[FILENAME_MAX];
  45     int fd;                             /* Closed after the finalize function. */
  46     gpg_error_t error;                  /* Returned from the NB function. */
  47 } pwmd_nb_status_t;
  48
  49 /*
  50  * A custom callback password retrieval function which is set with
  51  * pwmd_setopt().
  52  */
  53 typedef char *(*pwmd_password_fn)(pwm_t *pwm, void *data);
  54
  55 /*
  56  * A callback to be set with pwmd_setopt() that processes Assuan protocol
  57  * status messages. The 'line' is the status message prefixed with the
  58  * keyword.
  59  */
  60 typedef int (*pwmd_status_fn)(void *data, const char *line);
  61
  62 /*
  63  * A callback function that is passed to pwmd_inquire(). 'data' is user data
  64  * that was passed to pwmd_inquire(). 'keyword' is the same as the 'cmd'
  65  * argument to pwmd_inquire().
  66  *
  67  * 'rc' is the return code from assuan_send_data() and is initially 0 on the
  68  * first call to the set callback. This gives the client a chance to cleanup
  69  * if assuan_send_data() fails and should probably return the same error code,
  70  * if set, after doing so.
  71  *
  72  * 'result' should be set to the data to be sent which is of 'len' bytes. The
  73  * data is not modified.
  74  *
  75  * The function should return GPG_ERR_EOF when no more data needs to be sent,
  76  * 0 if there is more data pending or an error code which will terminate the
  77  * INQUIRE.
  78  */
  79 typedef gpg_error_t (*pwmd_inquire_fn)(void *data, const char *keyword,
  80         gpg_error_t rc, char **result, size_t *len);
  81
  82 typedef enum {
  83     /*
  84      * PWMD_OPTION_PASSWORD_FUNC
  85      *
  86      * Function to retrieve a password. This function should return an
  87      * string which is the password or NULL on error.
  88      */
  89     PWMD_OPTION_PASSWORD_FUNC,
  90
  91     /*
  92      * PWMD_OPTION_PASSWORD_DATA
  93      *
  94      * Data passed to the password function.
  95      */
  96     PWMD_OPTION_PASSWORD_DATA,
  97
  98     /*
  99      * PWMD_OPTION_PINENTRY
 100      *
 101      * The following argument should be of type int and set to 1 to enable the
 102      * use of pinentry(1) to retrieve passwords. Setting to 0 will disable
 103      * using pinentry and the password must be set with PWMD_OPTION_PASSWORD
 104      * or gotten from PWMD_OPTION_PASSWORD_FUNC.
 105      */
 106     PWMD_OPTION_PINENTRY,
 107
 108     /*
 109      * PWMD_OPTION_PINENTRY_TRIES
 110      *
 111      * The number of password tries before giving up. If the pinentry "Cancel"
 112      * button is selected, pinentry will abort. Must be > 0. The default is 3.
 113      */
 114     PWMD_OPTION_PINENTRY_TRIES,
 115
 116     /*
 117      * PWMD_OPTION_PINENTRY_PATH
 118      *
 119      * The full pathname to the pinentry program. If not specified,
 120      * /usr/bin/pinentry will be used.
 121      */
 122     PWMD_OPTION_PINENTRY_PATH,
 123
 124     /*
 125      * PWMD_OPTION_PINENTRY_TTY
 126      *
 127      * pinentry --ttyname.
 128      */
 129     PWMD_OPTION_PINENTRY_TTY,
 130
 131     /*
 132      * PWMD_OPTION_PINENTRY_DISPLAY
 133      *
 134      * pinentry --display
 135      */
 136     PWMD_OPTION_PINENTRY_DISPLAY,
 137
 138     /*
 139      * PWMD_OPTION_PINENTRY_TERM
 140      *
 141      * pinentry --ttytype
 142      */
 143     PWMD_OPTION_PINENTRY_TERM,
 144
 145     /*
 146      * PWMD_OPTION_PASSWORD
 147      *
 148      * The following argument should be of type char* which specifies the
 149      * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and
 150      * PWMD_OPTION_PINENTRY is 0. The password will be kept in memory until
 151      * pwmd_close() is called so setting this option isn't needed each time
 152      * pwmd_open() or pwmd_save() is called regardless of pwmd cache settings.
 153      */
 154     PWMD_OPTION_PASSWORD,
 155
 156     /*
 157      * PWMD_OPTION_PINENTRY_TITLE
 158      * PWMD_OPTION_PINENTRY_PROMPT
 159      * PWMD_OPTION_PINENTRY_DESC
 160      *
 161      * The following argument is of type char* which specifies either the
 162      * title, prompt or description in the pinentry program when
 163      * PWMD_OPTION_PINENTRY is set.
 164      */
 165      PWMD_OPTION_PINENTRY_TITLE,
 166      PWMD_OPTION_PINENTRY_PROMPT,
 167      PWMD_OPTION_PINENTRY_DESC,
 168
 169      /*
 170       * PWMD_OPTION_STATUS_FUNC
 171       *
 172       * A function to be called when a status line is sent from pwmd. This
 173       * function should return 0 on success or a gpg-error error code. This
 174       * function won't be used when getting a password with pinentry.
 175       */
 176      PWMD_OPTION_STATUS_FUNC,
 177
 178      /*
 179       * PWMD_OPTION_STATUS_DATA
 180       *
 181       * Data passed to the status function.
 182       */
 183      PWMD_OPTION_STATUS_DATA,
 184 } pwmd_option_t;
 185
 186 /*
 187  * Initialize the library. This sets up various things and must be called
 188  * before the other functions.
 189  */
 190 gpg_error_t pwmd_init(void);
 191
 192 /*
 193  * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
 194  * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
 195  * with the other functions or NULL if there was an error in which case
 196  * 'error' is set to an error code which may be described by pwmd_strerror().
 197  */
 198 pwm_t *pwmd_connect(const char *socket_path, gpg_error_t *error) __attribute__ ((warn_unused_result));
 199
 200 /*
 201  * Sets a libpwmd option 'opt'. The next argument should be of the data type
 202  * required for the option. Returns 0 on success or an error code.
 203  */
 204 gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...) __attribute__ ((warn_unused_result));
 205
 206 /*
 207  * Opens a file 'filename' (the OPEN command). The filename is not a full path
 208  * but only filename which is looked for in the pwmd configured data
 209  * directory. How the password is gotten depends on options set with
 210  * pwmd_setopt() and whether the file is cached on the server. Returns 0 on
 211  * success or an error code.
 212  */
 213 gpg_error_t pwmd_open(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result));
 214
 215 /*
 216  * This is like pwmd_open() but won't block the process when pinentry is used
 217  * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
 218  * on the server or if the file doesn't exist on the file system (a new file).
 219  * Otherwise it returns a file descriptor that select() can use. When ready
 220  * for a read, read() should read a pwmd_nb_status_t. If there is a system
 221  * error (pipe() or fork()), then -1 is returned and 'error' is set to an
 222  * error code that pwmd_strerror() can describe. See pwmd_open_nb_finalize().
 223  *
 224  * The 'timeout' parameter specifies the number of seconds until the pinentry
 225  * terminates. Setting to 0 (the default) will disable timeouts. Note that the
 226  * child process will reset the SIGALRM handler (if any) to it's own handler
 227  * and that the actual OPEN command isn't calculated as part of the elapsed
 228  * time.
 229  *
 230  * Be sure to set PWMD_OPTION_PINENTRY.
 231  */
 232 int pwmd_open_nb(pwm_t *pwm, gpg_error_t *error, const char *filename, int timeout) __attribute__ ((warn_unused_result));
 233
 234 /*
 235  * When a file descriptor has been returned from pwmd_open_nb() and after a
 236  * successful read(), you should call pwmd_open_nb_finalize() to update the
 237  * 'pwm' handle. If there was a pinentry or protocol error
 238  * pwmd_open_nb_finalize() will return an error code or 0 on success. Note
 239  * that pwmd_open_nb_finalize() will close the file descriptor returned from
 240  * pwmd_open_nb().
 241  */
 242 gpg_error_t pwmd_open_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 243
 244 /*
 245  * Sends the SAVE command to the associated handle 'pwm'. If a password is
 246  * required, how it is gotten depends on options set with pwmd_setopt().
 247  * Returns 0 on success or an error code.
 248  */
 249 gpg_error_t pwmd_save(pwm_t *pwm) __attribute__ ((warn_unused_result));
 250
 251 /*
 252  * This is like pwmd_save() but won't block the process when pinentry is used
 253  * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
 254  * on the server or if the file doesn't exist on the file system (a new file).
 255  * Otherwise it returns a file descriptor that select() can use. When ready
 256  * for a read, read() should read a pwmd_nb_status_t. If there is a system
 257  * error (pipe() or fork()), then -1 is returned and 'error' is set to an
 258  * error code that pwmd_strerror() can describe. See pwmd_save_nb_finalize().
 259  *
 260  * Note that there is no timeout setting. If a password is required, pinentry
 261  * won't timeout.
 262  *
 263  * Be sure to set PWMD_OPTION_PINENTRY.
 264  */
 265 int pwmd_save_nb(pwm_t *pwm, gpg_error_t *error) __attribute__ ((warn_unused_result));
 266
 267 /*
 268  * When a file descriptor has been returned from pwmd_save_nb() and after a
 269  * successful read(), you should call pwmd_save_nb_finalize() to update the
 270  * 'pwm' handle. If there was a pinentry or protocol error
 271  * pwmd_save_nb_finalize() will return an error code or 0 on success. Note
 272  * that pwmd_save_nb_finalize() will close the file descriptor returned from
 273  * pwmd_save_nb().
 274  */
 275 gpg_error_t pwmd_save_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
 276
 277 /*
 278  * Terminates a pinentry process. If your not using pwmd_open_nb() and want to
 279  * timeout the associated pinentry process, then call this function after your
 280  * timer has expired. Returns 0 on success or an error code.
 281  */
 282 gpg_error_t pwmd_terminate_pinentry(pwm_t *pwm) __attribute__ ((warn_unused_result));
 283
 284 /*
 285  * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
 286  * command fails an error code is returned which may be described by passing
 287  * the error to pwmd_strerror(). If successful the function returns 0 and the
 288  * 'result' is the character data of the command or NULL if there was none.
 289  *
 290  * For commands which use an INQUIRE (i.e., "STORE"), use pwmd_inquire() and
 291  * not pwmd_command().
 292  *
 293  * A note about the BYE command: Client's should not send this command
 294  * directly with pwmd_command(). They should use pwmd_close() instead because
 295  * libassuan will close the file descriptors with the associated context. This
 296  * is fine except when pwmd_close() is called. pwmd_close() calls
 297  * assuan_disconnect() which then sends the BYE command to the closed file
 298  * descriptor resulting in a segfault.
 299  */
 300 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...) __attribute__ ((warn_unused_result));
 301
 302 /*
 303  * Commands which use an INQUIRE to send data should use this function and not
 304  * pwmd_command(). 'cmd' is the command to send and is also the 'keyword'
 305  * argument to the callback function 'func'. 'data' is user data passed to the
 306  * callback function. Returnes 0 on success or and error code which may have
 307  * been returned from the callback function.
 308  */
 309 gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd, pwmd_inquire_fn func,
 310         void *data) __attribute__ ((warn_unused_result));
 311
 312 /*
 313  * Free's the memory used by the result of pwmd_command() if any. It is
 314  * important to use this function because libpwmd keeps track of all memory
 315  * de/allocations.
 316  */
 317 void pwmd_free_result(void *);
 318
 319 /*
 320  * Closes the connection to the socket and frees the resources of the handle.
 321  * Returns no value.
 322  */
 323 void pwmd_close(pwm_t *pwm);
 324
 325 /*
 326  * Protocol error codes.
 327  */
 328 #define EPWMD_KEY               GPG_ERR_WRONG_KEY_USAGE
 329 #define EPWMD_BADKEY            GPG_ERR_INV_PASSPHRASE
 330 #define EPWMD_COMMAND_SYNTAX    GPG_ERR_SYNTAX
 331 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_NOT_FOUND
 332 #define EPWMD_ACCOUNT_EXISTS    GPG_ERR_AMBIGUOUS_NAME
 333 #define EPWMD_CACHE_NOT_FOUND   GPG_ERR_NOT_FOUND
 334 #define EPWMD_ATTR_SYNTAX       GPG_ERR_SYNTAX
 335 #define EPWMD_ATTR_NOT_FOUND    GPG_ERR_NOT_FOUND
 336 #define EPWMD_INVALID_FILENAME  GPG_ERR_INV_NAME
 337 #define EPWMD_EMPTY_ELEMENT     GPG_ERR_NO_VALUE
 338 #define EPWMD_INVALID_ELEMENT   GPG_ERR_INV_VALUE
 339 #define EPWMD_ERROR             GPG_ERR_USER_1
 340 #define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
 341 #define EPWMD_LOOP              GPG_ERR_USER_3
 342 #define EPWMD_NO_FILE           GPG_ERR_USER_4
 343 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_5
 344 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_6
 345 #define EPWMD_MAX               GPG_ERR_USER_7
 346
 347 /*
 348  * Return a string describing a pwmd protocol error code.
 349  */
 350 const char *pwmd_strerror(gpg_error_t error);
 351
 352 #ifdef __cplusplus
 353 }
 354 #endif
 355
 356 #endif