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 char *(pwmd_password_func)(void *data);
  34
  35 typedef enum {
  36     /*
  37      * PWMD_OPTION_PASSWORD_FUNC
  38      *
  39      * Function to retrieve a password. This function should return an
  40      * allocated string which is the password or NULL.
  41      */
  42     PWMD_OPTION_PASSWORD_FUNC,
  43
  44     /*
  45      * PWMD_OPTION_PASSWORD_DATA
  46      *
  47      * Data passed to the password function.
  48      */
  49     PWMD_OPTION_PASSWORD_DATA,
  50
  51     /*
  52      * PWMD_OPTION_USEAGENT
  53      *
  54      * The following argument should be of type int and set to 1 to enable
  55      * the use of gpg-agent to retrieve passwords. Setting to 0 will disable
  56      * using gpg-agent and the password must be set with PWMD_OPTION_PASSWORD
  57      * or gotten from PWMD_OPTION_PASSWORD_FUNC.
  58      */
  59     PWMD_OPTION_USEAGENT,
  60
  61     /*
  62      * PWMD_OPTION_PASSWORD
  63      *
  64      * The following argument should be of type char* which specifies the
  65      * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and
  66      * PWMD_OPTION_USEAGENT is 0.
  67      */
  68     PWMD_OPTION_PASSWORD,
  69
  70     /*
  71      * PWMD_OPTION_TITLE
  72      * PWMD_OPTION_PROMPT
  73      * PWMD_OPTION_DESC
  74      *
  75      * The following argument is of type char* which specifies either the
  76      * title, prompt or description in the pinentry program when
  77      * PWMD_OPTION_USEAGENT is set.
  78      */
  79      PWMD_OPTION_TITLE,
  80      PWMD_OPTION_PROMPT,
  81      PWMD_OPTION_DESC,
  82 } pwmd_option;
  83
  84 /*
  85  * Valid protocol commands for use with pwmd_command(). The data type for the
  86  * result parameter of pwmd_command() (if successful) is described below along
  87  * with the argument data types for each command. See pwmd_command() for the
  88  * return value.
  89  */
  90 typedef enum {
  91     /*
  92      * PWMD_OPEN
  93      *
  94      * A result of NULL if successful. The only argument is of type char*
  95      * which is the filename to open. The password used to open the file is
  96      * set with the PWMD_SETOPT command.
  97      */
  98     PWMD_OPEN,
  99
 100     /*
 101      * PWMD_SETOPT
 102      *
 103      * Sets library and other options. See pwmd_option above for available
 104      * options.
 105      */
 106     PWMD_SETOPT,
 107
 108     /*
 109      * PWMD_SAVE
 110      *
 111      * A result of NULL if successful. Takes no arguments. The password is set
 112      * using the PWMD_SETOPT command (see above).
 113      */
 114     PWMD_SAVE,
 115
 116     /*
 117      * PWMD_COMMAND
 118      *
 119      * A result of char* if successful. Sends a protocol command. The next
 120      * argument is of type char* and is the command and any arguments
 121      * including the newline character.
 122      */
 123     PWMD_COMMAND,
 124 } pwmd_cmd;
 125
 126 typedef struct {
 127     int fd;
 128     void *ctx;          // the assuan handle
 129     char cache_id[16];
 130     int use_agent;
 131     char *title;
 132     char *prompt;
 133     char *desc;
 134     char *password;
 135     char *filename;
 136     pwmd_password_func *passfunc;
 137     void *passdata;
 138 } pwm_t;
 139
 140 /*
 141  * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
 142  * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
 143  * with the other functions or NULL if there was an error in which case
 144  * 'error' is set to the errno of the error.
 145  */
 146 pwm_t *pwmd_connect(const char *socket_path, int *error);
 147
 148 /*
 149  * Closes the connection to the socket and frees the resources of the handle.
 150  * Returns no value.
 151  */
 152 void pwmd_close(pwm_t *pwm);
 153
 154 /*
 155  * Sends a command 'cmd' to the daemon using handle 'pwm'. If the command
 156  * fails (the return value is not PWMD_OK) and the return value is
 157  * PWMD_PERROR, the result is set to NULL and error is set to a protocol error
 158  * code. If the return value is PWMD_ERROR, the result is set to NULL and
 159  * error is set to the errno of the error. If using gpg-agent to get the
 160  * password and there is an error connecting to gpg-agent, PWMD_AGENT_ERROR is
 161  * returned and error is set to EPWMD_ERROR. If successful the function
 162  * returns PWMD_OK and the result is the character data of the command or NULL
 163  * if there was none.
 164  */
 165 int pwmd_command(pwm_t *pwm, char **result, int *error, pwmd_cmd cmd, ...);
 166
 167 /*
 168  * Protocol error codes.
 169  */
 170 #define EPWMD_ERROR             0
 171 #define EPWMD_INVALID_FILENAME  1
 172 #define EPWMD_MAX_SLOTS         2
 173 #define EPWMD_KEY               3
 174 #define EPWMD_BADKEY            4
 175 #define EPWMD_COMMAND_SYNTAX    5
 176 #define EPWMD_ELEMENT_NOT_FOUND 6
 177 #define EPWMD_TRAILING_ELEMENT  7
 178 #define EPWMD_INVALID_ELEMENT   8
 179 #define EPWMD_ROOT_TEXT_ELEMENT 9
 180 #define EPWMD_EMPTY_ELEMENT     10
 181 #define EPWMD_ATTR_SYNTAX       11
 182 #define EPWMD_ACCOUNT_EXISTS    12
 183 #define EPWMD_FILE_NOT_FOUND    13
 184 #define EPWMD_NO_FILE           14
 185 #define EPWMD_FILE_OPENED       15
 186 #define EPWMD_LIBXML_ERROR      16
 187 #define EPWMD_CACHE_NOT_FOUND   17
 188 #define EPWMD_ATTR_NOT_FOUND    18
 189 #define EPWMD_NOT_A_FILE        19
 190 #define EPWMD_FILE_MODIFIED     20
 191 #define EPWMD_MAX               21
 192
 193 /*
 194  * Return a string describing a pwmd protocol error code.
 195  */
 196 const char *pwmd_strerror(int pwmd_error);
 197
 198 #ifdef __cplusplus
 199 }
 200 #endif
 201
 202 #endif