libpwmd.h

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