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