libpwmd/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 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 typedef enum {
  27     PWMD_ERROR = -1,    // file access, memory allocation and other errors
  28     PWMD_OK,
  29     PWMD_PERROR,        // protocol error
  30     PWMD_AGENT_ERROR,   // gpg-agent error
  31 } pwmd_state;
  32
  33 typedef enum {
  34     /*
  35      * PWMD_OPTION_USEAGENT
  36      *
  37      * The following argument should be of type int and set to 1 to enable
  38      * the use of gpg-agent to retrieve passwords. Setting to 0 will disable
  39      * using gpg-agent and the password must be set with PWMD_OPTION_PASSWORD.
  40      */
  41     PWMD_OPTION_USEAGENT,
  42
  43     /*
  44      * PWMD_OPTION_PASSWORD
  45      *
  46      * The following argument should be of type char* which specifies the
  47      * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued.
  48      */
  49     PWMD_OPTION_PASSWORD,
  50
  51     /*
  52      * PWMD_OPTION_TITLE
  53      * PWMD_OPTION_PROMPT
  54      * PWMD_OPTION_DESC
  55      *
  56      * The following argument is of type char* which specifies either the
  57      * title, prompt or description in the pinentry program when
  58      * PWMD_OPTION_USEAGENT is set.
  59      */
  60      PWMD_OPTION_TITLE,
  61      PWMD_OPTION_PROMPT,
  62      PWMD_OPTION_DESC,
  63 } pwmd_option;
  64
  65 typedef enum {
  66     /*
  67      * PWMD_CACHE_ISCACHED
  68      *
  69      * Tests whether the following char* argument, being a filename, has it's
  70      * password cached.
  71      */
  72     PWMD_CACHE_ISCACHED,
  73
  74     /*
  75      * PWMD_CACHE_CLEAR
  76      *
  77      * The following argument should be of type char* which specifies a
  78      * filename and the associated password to remove from the cache.
  79      */
  80     PWMD_CACHE_CLEAR,
  81
  82     /*
  83      * PWMD_CACHE_CLEARALL
  84      *
  85      * Takes no arguments. Clears the entire file cache. Always returns
  86      * successfully. The next OPEN or SAVE command will require a key.
  87      */
  88     PWMD_CACHE_CLEARALL,
  89 } pwmd_cache_cmd;
  90
  91 /*
  92  * Valid protocol commands for use with pwmd_command(). The data type for the
  93  * result parameter of pwmd_command() (if successful) is described below along
  94  * with the argument data types for each command. See pwmd_command() for the
  95  * return value.
  96  */
  97 typedef enum {
  98     /*
  99      * PWMD_CACHE
 100      *
 101      * A result of NULL if successful. The next argument should be of type
 102      * pwmd_cache_cmd. If PWMD_CACHE_CLEAR or PWMD_CACHE_ISCACHED, the
 103      * following argument should be of type char* specifying the filename.
 104      */
 105     PWMD_CACHE,
 106
 107     /*
 108      * PWMD_OPEN
 109      *
 110      * A result of NULL if successful. The only argument is of type char*
 111      * which is the filename to open. The password used to open the file is
 112      * set with the PWMD_SETOPT command.
 113      */
 114     PWMD_OPEN,
 115
 116     /*
 117      * PWMD_LIST
 118      *
 119      * The result is a NULL terminated array of character pointers (char**)
 120      * which are account names which should be free()'d. Takes no arguments.
 121      */
 122     PWMD_LIST,
 123
 124     /*
 125      * PWMD_LIST_ACCOUNT
 126      *
 127      * The result is a NULL terminated array of character pointers (char**)
 128      * which are elements in the specified element path in the following char*
 129      * argument. The result should be free()'d.
 130      */
 131     PWMD_LIST_ACCOUNT,
 132
 133     /*
 134      * PWMD_GET
 135      *
 136      * The result is of type char* being value of the following char* element
 137      * path argument which should be free()'d.
 138      */
 139     PWMD_GET,
 140
 141     /*
 142      * PWMD_STORE
 143      *
 144      * A NULL result if successful. Stores a new element path. The argument
 145      * should be of type char* which specifies the element path. The last
 146      * element in the element path is the element value which should be base
 147      * 64 encoded to prevent XML and pwmd element parsing errors, though not
 148      * required.
 149      */
 150     PWMD_STORE,
 151
 152     /*
 153      * PWMD_DELETE
 154      *
 155      * A NULL result if successful. Deletes a single element or entire element
 156      * tree. The argument should be of type char* which specifies an element
 157      * path.
 158      */
 159     PWMD_DELETE,
 160
 161     /*
 162      * PWMD_ATTR_SET
 163      *
 164      * Sets an attribute for an element. The next argument should be of type
 165      * char* which is the name of the attribute, followed by the char* element
 166      * path to store the attrbute, followed by the char* attribute value.
 167      */
 168     PWMD_ATTR_SET,
 169
 170     /*
 171      * PWMD_ATTR_GET
 172      *
 173      * Gets an attribute for an element. The next argument should be of type
 174      * char* which is the name of the attribute, followed by an argument of
 175      * type char* which is the element path. The result will be of type char*
 176      * if successful and should be free()'d.
 177      */
 178     PWMD_ATTR_GET,
 179
 180     /*
 181      * PWMD_ATTR_DELETE
 182      *
 183      * Removes the named attribute from an element path. The next argument
 184      * is of type char* which is the name of the attribute followed by an
 185      * argument of type char* which is the element path.
 186      */
 187     PWMD_ATTR_DELETE,
 188
 189     /*
 190      * PWMD_ATTR_LIST
 191      *
 192      * The result is of type char** and is a list of attributes for the
 193      * following char* element path. The result should be free()'d.
 194      */
 195     PWMD_ATTR_LIST,
 196
 197     /*
 198      * PWMD_SETOPT
 199      *
 200      * Sets library and other options. See pwmd_option above for available
 201      * options.
 202      */
 203     PWMD_SETOPT,
 204
 205     /*
 206      * PWMD_SAVE
 207      *
 208      * A result of NULL if successful. Takes no arguments. The password is set
 209      * using the PWMD_SETOPT command (see above).
 210      */
 211     PWMD_SAVE,
 212
 213     /*
 214      * PWMD_DUMP
 215      *
 216      * The result is of type char* and is the in memory document on the
 217      * server which should be free()'d.
 218      */
 219     PWMD_DUMP,
 220
 221     /*
 222      * PWMD_QUIT
 223      *
 224      * A result of NULL if successful. Takes no arguments.
 225      */
 226     PWMD_QUIT,
 227
 228     /*
 229      * PWMD_RAW
 230      *
 231      * A result of char* if successful. Sends a raw protocol command. The next
 232      * argument is of type char* and is the command and any arguments
 233      * including a newline character.
 234      */
 235     PWMD_RAW,
 236 } pwmd_cmd;
 237
 238 typedef struct {
 239     int fd;
 240     void *ctx;          // the assuan handle
 241     char cache_id[16];
 242     int use_agent;
 243     char *title;
 244     char *prompt;
 245     char *desc;
 246     char *password;
 247     char *filename;
 248 } pwm_t;
 249
 250 /*
 251  * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
 252  * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
 253  * with the other functions or NULL if there was an error in which case
 254  * 'error' is set to the errno of the error.
 255  */
 256 pwm_t *pwmd_connect(const char *socket_path, int *error);
 257
 258 /*
 259  * Closes the connection to the socket and frees the resources of the handle.
 260  * Returns no value.
 261  */
 262 void pwmd_close(pwm_t *pwm);
 263
 264 /*
 265  * Sends a command 'cmd' to the daemon using handle 'pwm'. If the command
 266  * fails (the return value is not PWMD_OK) and the return value is
 267  * PWMD_PERROR, the result is set to NULL and error is set to a protocol error
 268  * code. If the return value is PWMD_ERROR, the result is set to NULL and
 269  * error is set to the errno of the error. If using gpg-agent to get the
 270  * password and there is an error connecting to gpg-agent, PWMD_AGENT_ERROR is
 271  * returned and error is set to EPWMD_ERROR. If successful the function
 272  * returns PWMD_OK and the result is of the data type specific to the command
 273  * which is described above in the pwmd_cmd enumeration.
 274  */
 275 int pwmd_command(pwm_t *pwm, void **result, int *error, pwmd_cmd cmd, ...);
 276
 277 /*
 278  * Frees a list result.
 279  */
 280 void pwmd_list_free(char **list);
 281
 282 // FIXME read the RFC to remove the glib dependency (???).
 283 /*
 284  * Returns the decoded string which should be free()'d.
 285  */
 286 unsigned char *pwmd_base64_decode(const char *str, size_t *size);
 287
 288 /*
 289  * Returns the encoded string which should be free()'d.
 290  */
 291 char *pwmd_base64_encode(const char *str, size_t len);
 292
 293 /*
 294  * Protocol error codes.
 295  */
 296 #define EPWMD_ERROR             0
 297 #define EPWMD_INVALID_FILENAME  1
 298 #define EPWMD_MAX_SLOTS         2
 299 #define EPWMD_KEY               3
 300 #define EPWMD_BADKEY            4
 301 #define EPWMD_COMMAND_SYNTAX    5
 302 #define EPWMD_ELEMENT_NOT_FOUND 6
 303 #define EPWMD_TRAILING_ELEMENT  7
 304 #define EPWMD_INVALID_ELEMENT   8
 305 #define EPWMD_ROOT_TEXT_ELEMENT 9
 306 #define EPWMD_EMPTY_ELEMENT     10
 307 #define EPWMD_ATTR_SYNTAX       11
 308 #define EPWMD_ACCOUNT_EXISTS    12
 309 #define EPWMD_FILE_NOT_FOUND    13
 310 #define EPWMD_NO_FILE           14
 311 #define EPWMD_FILE_OPENED       15
 312 #define EPWMD_LIBXML_ERROR      16
 313 #define EPWMD_CACHE_NOT_FOUND   17
 314 #define EPWMD_ATTR_NOT_FOUND    18
 315 #define EPWMD_NOT_A_FILE        19
 316 #define EPWMD_MAX               20
 317
 318 /*
 319  * Return a string describing a pwmd protocol error code.
 320  */
 321 const char *pwmd_strerror(int pwmd_error);
 322
 323 #ifdef __cplusplus
 324 }
 325 #endif
 326
 327 #endif