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 #include <assuan.h>
  23 #include <gpg-error.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 struct pwm_s;
  30 typedef struct pwm_s pwm_t;
  31
  32 typedef enum {
  33     PWMD_OK,
  34     PWMD_ERROR,
  35 } pwmd_error_t;
  36
  37 typedef char *(*pwmd_password_func)(void *data);
  38 typedef int (*pwmd_status_func)(void *data, const char *line);
  39
  40 typedef enum {
  41     /*
  42      * PWMD_OPTION_PASSWORD_FUNC
  43      *
  44      * Function to retrieve a password. This function should return an
  45      * allocated string which is the password or NULL.
  46      */
  47     PWMD_OPTION_PASSWORD_FUNC,
  48
  49     /*
  50      * PWMD_OPTION_PASSWORD_DATA
  51      *
  52      * Data passed to the password function.
  53      */
  54     PWMD_OPTION_PASSWORD_DATA,
  55
  56     /*
  57      * PWMD_OPTION_PINENTRY
  58      *
  59      * The following argument should be of type int and set to 1 to enable the
  60      * use of pinentry(1) to retrieve passwords. Setting to 0 will disable
  61      * using pinentry and the password must be set with PWMD_OPTION_PASSWORD
  62      * or gotten from PWMD_OPTION_PASSWORD_FUNC.
  63      */
  64     PWMD_OPTION_PINENTRY,
  65
  66     /*
  67      * PWMD_OPTION_PINENTRY_TRIES
  68      *
  69      * The number of password tries before giving up. If the pinentry "Cancel"
  70      * button is selected, pinentry will abort. Must be > 0. The default is 3.
  71      */
  72     PWMD_OPTION_PINENTRY_TRIES,
  73
  74     /*
  75      * PWMD_OPTION_PINENTRY_PATH
  76      *
  77      * The full pathname to the pinentry program. If not specified,
  78      * /usr/bin/pinentry will be used.
  79      */
  80     PWMD_OPTION_PINENTRY_PATH,
  81
  82     /*
  83      * PWMD_OPTION_PINENTRY_TTY
  84      *
  85      * pinentry --ttyname.
  86      */
  87     PWMD_OPTION_PINENTRY_TTY,
  88
  89     /*
  90      * PWMD_OPTION_PINENTRY_DISPLAY
  91      *
  92      * pinentry --display
  93      */
  94     PWMD_OPTION_PINENTRY_DISPLAY,
  95
  96     /*
  97      * PWMD_OPTION_PINENTRY_TERM
  98      *
  99      * pinentry --ttytype
 100      */
 101     PWMD_OPTION_PINENTRY_TERM,
 102
 103     /*
 104      * PWMD_OPTION_PASSWORD
 105      *
 106      * The following argument should be of type char* which specifies the
 107      * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and
 108      * PWMD_OPTION_PINENTRY is 0.
 109      */
 110     PWMD_OPTION_PASSWORD,
 111
 112     /*
 113      * PWMD_OPTION_PINENTRY_TITLE
 114      * PWMD_OPTION_PINENTRY_PROMPT
 115      * PWMD_OPTION_PINENTRY_DESC
 116      *
 117      * The following argument is of type char* which specifies either the
 118      * title, prompt or description in the pinentry program when
 119      * PWMD_OPTION_PINENTRY is set.
 120      */
 121      PWMD_OPTION_PINENTRY_TITLE,
 122      PWMD_OPTION_PINENTRY_PROMPT,
 123      PWMD_OPTION_PINENTRY_DESC,
 124
 125      /*
 126       * PWMD_OPTION_STATUS_FUNC
 127       *
 128       * A function to be called when a status line is sent from pwmd. This
 129       * function should return 0 on success or a gpg-error error code. This
 130       * function won't be used when getting a password with pinentry.
 131       */
 132      PWMD_OPTION_STATUS_FUNC,
 133
 134      /*
 135       * PWMD_OPTION_STATUS_DATA
 136       *
 137       * Data passed to the status function.
 138       */
 139      PWMD_OPTION_STATUS_DATA,
 140 } pwmd_option_t;
 141
 142 /*
 143  * Initialize the library.
 144  */
 145 pwmd_error_t pwmd_init(void);
 146
 147 /*
 148  * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
 149  * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
 150  * with the other functions or NULL if there was an error in which case
 151  * 'error' is set to an error code which may be described by pwmd_strerror().
 152  */
 153 pwm_t *pwmd_connect(const char *socket_path, gpg_error_t *error);
 154
 155 /*
 156  * Opens a file 'filename' (the OPEN command). The password is gotten from the
 157  * pinentry program if configured to do so and not already cached. Returnes
 158  * PWMD_OK on success or PWMD_ERROR on error and sets 'error' to the error
 159  * code.
 160  */
 161 pwmd_error_t pwmd_open(pwm_t *pwm, gpg_error_t *error, const char *filename);
 162
 163 /*
 164  * Send's the SAVE command and takes care of password requests.
 165  */
 166 pwmd_error_t pwmd_save(pwm_t *pwm, gpg_error_t *error);
 167
 168 /*
 169  * Closes the connection to the socket and frees the resources of the handle.
 170  * Returns no value.
 171  */
 172 void pwmd_close(pwm_t *pwm);
 173
 174 /*
 175  * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
 176  * command fails PWMD_ERROR is returned with 'error' set to the error code
 177  * which may be described by passing the error to pwmd_strerror(). If
 178  * successful the function returns PWMD_OK and the 'result' is the character
 179  * data of the command or NULL if there was none.
 180  *
 181  * A note about the BYE command: Client's should not send this command
 182  * directly with pwmd_command(). They should use pwmd_close() instead because
 183  * libassuan will close the file descriptors with the associated context. This
 184  * is fine except when pwmd_close() is called. pwmd_close() calls
 185  * assuan_disconnect() which then send's the BYE command to the closed file
 186  * descriptor resulting in a segfault.
 187  */
 188 pwmd_error_t pwmd_command(pwm_t *pwm, char **result, gpg_error_t *error, const char *cmd, ...);
 189
 190 /*
 191  * Free's the memory used by the result of pwmd_command() if any. It is
 192  * important to use this function because libpwmd keeps track of all memory
 193  * de/allocations.
 194  */
 195 void pwmd_free_result(void *);
 196
 197 /*
 198  * Sets a libpwmd option 'opt'. The next argument should be of the data type
 199  * required for the option. Return PWMD_OK on success or PWMD_ERROR if 'opt'
 200  * is an invalid option.
 201  */
 202 pwmd_error_t pwmd_setopt(pwm_t *pwm, gpg_error_t *error, pwmd_option_t opt, ...);
 203
 204 /*
 205  * This a nonblocking pinentry password retriever. It returns -2 when
 206  * 'filename' is not NULL and is cached (ISCACHED) or if the file doesn't
 207  * exist on the file system (a new file). If 'filename' is NULL or the file is
 208  * not cached this function returns a file descriptor that select() can use.
 209  * When ready for read(), read() should read a pwmd_password_s. If a pinentry
 210  * error occurs, the structure member .error will be set to the error code. If
 211  * theres a system error (pipe() or fork()), then -1 is returned and 'error'
 212  * is set to an error code that pwmd_strerror() can describe.
 213  */
 214 typedef struct {
 215     char password[ASSUAN_LINELENGTH];
 216     gpg_error_t error;
 217 } pwmd_password_t;
 218
 219 int pwmd_get_password(pwm_t *pwm, gpg_error_t *error, const char *filename);
 220
 221 /*
 222  * Protocol error codes.
 223  */
 224 #define EPWMD_ERROR             GPG_ERR_USER_1
 225 #define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
 226 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_USER_3
 227 #define EPWMD_TRAILING_ELEMENT  GPG_ERR_USER_4
 228 #define EPWMD_INVALID_ELEMENT   GPG_ERR_USER_5
 229 #define EPWMD_EMPTY_ELEMENT     GPG_ERR_USER_6
 230 #define EPWMD_ACCOUNT_EXISTS    GPG_ERR_USER_7
 231 #define EPWMD_FILE_NOT_FOUND    GPG_ERR_USER_8
 232 #define EPWMD_NO_FILE           GPG_ERR_USER_9
 233 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_10
 234 #define EPWMD_CACHE_NOT_FOUND   GPG_ERR_USER_11
 235 #define EPWMD_ATTR_NOT_FOUND    GPG_ERR_USER_12
 236 #define EPWMD_INVALID_FILENAME  GPG_ERR_USER_13
 237 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_14
 238 #define EPWMD_MAX               GPG_ERR_USER_15
 239
 240 /*
 241  * Try to reuse GPG error codes when possible. There's only 16 user-defined
 242  * codes available.
 243  */
 244 #define EPWMD_KEY               GPG_ERR_WRONG_KEY_USAGE
 245 #define EPWMD_BADKEY            GPG_ERR_INV_PASSPHRASE
 246 #define EPWMD_COMMAND_SYNTAX    GPG_ERR_SYNTAX
 247 #define EPWMD_ATTR_SYNTAX       GPG_ERR_SYNTAX
 248
 249 /*
 250  * Return a string describing a pwmd protocol error code.
 251  */
 252 const char *pwmd_strerror(gpg_error_t error);
 253
 254 #ifdef __cplusplus
 255 }
 256 #endif
 257
 258 #endif