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