Added a 'deb' Makefile target.
[libpwmd.git] / libpwmd.h
blob5118fb947dc44d8bfd7a28494428013e33e340bc
1 /* vim:tw=78:ts=8:sw=4:set ft=c: */
2 /*
3 Copyright (C) 2006-2007 Ben Kibbey <bjk@luxsci.net>
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.
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.
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
19 #ifndef LIBPWMD_H
20 #define LIBPWMD_H
22 #include <assuan.h>
23 #include <gpg-error.h>
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
29 struct pwm_s;
30 typedef struct pwm_s pwm_t;
32 typedef struct {
33 char filename[FILENAME_MAX];
34 int fd;
35 gpg_error_t error;
36 } pwmd_nb_status_t;
38 typedef char *(*pwmd_password_fn)(pwm_t *pwm, void *data);
39 typedef int (*pwmd_status_fn)(void *data, const char *line);
41 typedef enum {
43 * PWMD_OPTION_PASSWORD_FUNC
45 * Function to retrieve a password. This function should return an
46 * string which is the password or NULL on error.
48 PWMD_OPTION_PASSWORD_FUNC,
51 * PWMD_OPTION_PASSWORD_DATA
53 * Data passed to the password function.
55 PWMD_OPTION_PASSWORD_DATA,
58 * PWMD_OPTION_PINENTRY
60 * The following argument should be of type int and set to 1 to enable the
61 * use of pinentry(1) to retrieve passwords. Setting to 0 will disable
62 * using pinentry and the password must be set with PWMD_OPTION_PASSWORD
63 * or gotten from PWMD_OPTION_PASSWORD_FUNC.
65 PWMD_OPTION_PINENTRY,
68 * PWMD_OPTION_PINENTRY_TRIES
70 * The number of password tries before giving up. If the pinentry "Cancel"
71 * button is selected, pinentry will abort. Must be > 0. The default is 3.
73 PWMD_OPTION_PINENTRY_TRIES,
76 * PWMD_OPTION_PINENTRY_PATH
78 * The full pathname to the pinentry program. If not specified,
79 * /usr/bin/pinentry will be used.
81 PWMD_OPTION_PINENTRY_PATH,
84 * PWMD_OPTION_PINENTRY_TTY
86 * pinentry --ttyname.
88 PWMD_OPTION_PINENTRY_TTY,
91 * PWMD_OPTION_PINENTRY_DISPLAY
93 * pinentry --display
95 PWMD_OPTION_PINENTRY_DISPLAY,
98 * PWMD_OPTION_PINENTRY_TERM
100 * pinentry --ttytype
102 PWMD_OPTION_PINENTRY_TERM,
105 * PWMD_OPTION_PASSWORD
107 * The following argument should be of type char* which specifies the
108 * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and
109 * PWMD_OPTION_PINENTRY is 0.
111 PWMD_OPTION_PASSWORD,
114 * PWMD_OPTION_PINENTRY_TITLE
115 * PWMD_OPTION_PINENTRY_PROMPT
116 * PWMD_OPTION_PINENTRY_DESC
118 * The following argument is of type char* which specifies either the
119 * title, prompt or description in the pinentry program when
120 * PWMD_OPTION_PINENTRY is set.
122 PWMD_OPTION_PINENTRY_TITLE,
123 PWMD_OPTION_PINENTRY_PROMPT,
124 PWMD_OPTION_PINENTRY_DESC,
127 * PWMD_OPTION_STATUS_FUNC
129 * A function to be called when a status line is sent from pwmd. This
130 * function should return 0 on success or a gpg-error error code. This
131 * function won't be used when getting a password with pinentry.
133 PWMD_OPTION_STATUS_FUNC,
136 * PWMD_OPTION_STATUS_DATA
138 * Data passed to the status function.
140 PWMD_OPTION_STATUS_DATA,
141 } pwmd_option_t;
144 * Initialize the library.
146 gpg_error_t pwmd_init(void);
149 * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
150 * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
151 * with the other functions or NULL if there was an error in which case
152 * 'error' is set to an error code which may be described by pwmd_strerror().
154 pwm_t *pwmd_connect(const char *socket_path, gpg_error_t *error);
157 * Opens a file 'filename' (the OPEN command). The password is gotten from the
158 * pinentry program if configured to do so and not already cached. Returnes
159 * 0 on success or an error code.
161 gpg_error_t pwmd_open(pwm_t *pwm, const char *filename);
164 * This a nonblocking way of opening a file. It returns -2 when the file is
165 * cached (ISCACHED) on the server or if the file doesn't exist on the file
166 * system (a new file). Otherwise it returns a file descriptor that select()
167 * can use. When ready for a read, read() should read a pwmd_nb_status_t. If
168 * there is a system error (pipe() or fork()), then -1 is returned and 'error'
169 * is set to an error code that pwmd_strerror() can describe.
171 * When a file descriptor has been returned from pwmd_open_nb() and after a
172 * successful read(), the caller should use pwmd_open_nb_finalize() to update
173 * the 'pwm' handle. If there was a pinentry or protocol error
174 * pwmd_open_nb_finalize() will return an error code or 0 on success.
176 * The 'timeout' parameter specifies the number of seconds until the pinentry
177 * terminates. Setting to 0 (the default) will disable timeouts. Note that the
178 * child process will reset the SIGALRM handler (if any) to it's own handler
179 * and that the actual OPEN command isn't calculated as part of the elapsed
180 * time.
182 * Be sure to set PWMD_OPTION_PINENTRY.
184 int pwmd_open_nb(pwm_t *pwm, gpg_error_t *error, const char *filename, int timeout);
185 gpg_error_t pwmd_open_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status);
188 * Send's the SAVE command and takes care of password requests.
190 gpg_error_t pwmd_save(pwm_t *pwm);
193 * Send's the SAVE protocol command without pinentry blocking the process. It
194 * act's like pwmd_open_nb() above, but doesn't require a filename. The caller
195 * should use pwmd_save_nb_finalize() when a file descriptor is returned from
196 * pwmd_save_nb() and after a successful read().
198 * Be sure to set PWMD_OPTION_PINENTRY.
200 int pwmd_save_nb(pwm_t *pwm, gpg_error_t *error);
201 gpg_error_t pwmd_save_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status);
204 * Terminates a pinentry process. If your not using pwmd_open_nb() and want to
205 * timeout a password entry, then call this function after your timer has
206 * expired. Returns 0 on success or an error code.
208 gpg_error_t pwmd_terminate_pinentry(pwm_t *pwm);
211 * Closes the connection to the socket and frees the resources of the handle.
212 * Returns no value.
214 void pwmd_close(pwm_t *pwm);
217 * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
218 * command fails an error code is returned which may be described by passing
219 * the error to pwmd_strerror(). If successful the function returns 0 and the
220 * 'result' is the character data of the command or NULL if there was none.
222 * A note about the BYE command: Client's should not send this command
223 * directly with pwmd_command(). They should use pwmd_close() instead because
224 * libassuan will close the file descriptors with the associated context. This
225 * is fine except when pwmd_close() is called. pwmd_close() calls
226 * assuan_disconnect() which then send's the BYE command to the closed file
227 * descriptor resulting in a segfault.
229 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...);
232 * Free's the memory used by the result of pwmd_command() if any. It is
233 * important to use this function because libpwmd keeps track of all memory
234 * de/allocations.
236 void pwmd_free_result(void *);
239 * Sets a libpwmd option 'opt'. The next argument should be of the data type
240 * required for the option. Returns 0 on success or an error code.
242 gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...);
245 * Protocol error codes.
247 #define EPWMD_ERROR GPG_ERR_USER_1
248 #define EPWMD_MAX_SLOTS GPG_ERR_USER_2
249 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_USER_3
250 #define EPWMD_TRAILING_ELEMENT GPG_ERR_USER_4
251 #define EPWMD_INVALID_ELEMENT GPG_ERR_USER_5
252 #define EPWMD_EMPTY_ELEMENT GPG_ERR_USER_6
253 #define EPWMD_ACCOUNT_EXISTS GPG_ERR_USER_7
254 #define EPWMD_FILE_NOT_FOUND GPG_ERR_USER_8
255 #define EPWMD_NO_FILE GPG_ERR_USER_9
256 #define EPWMD_LIBXML_ERROR GPG_ERR_USER_10
257 #define EPWMD_CACHE_NOT_FOUND GPG_ERR_USER_11
258 #define EPWMD_ATTR_NOT_FOUND GPG_ERR_USER_12
259 #define EPWMD_INVALID_FILENAME GPG_ERR_USER_13
260 #define EPWMD_FILE_MODIFIED GPG_ERR_USER_14
261 #define EPWMD_MAX GPG_ERR_USER_15
264 * Try to reuse GPG error codes when possible. There's only 16 user-defined
265 * codes available.
267 #define EPWMD_KEY GPG_ERR_WRONG_KEY_USAGE
268 #define EPWMD_BADKEY GPG_ERR_INV_PASSPHRASE
269 #define EPWMD_COMMAND_SYNTAX GPG_ERR_SYNTAX
270 #define EPWMD_ATTR_SYNTAX GPG_ERR_SYNTAX
273 * Return a string describing a pwmd protocol error code.
275 const char *pwmd_strerror(gpg_error_t error);
277 #ifdef __cplusplus
279 #endif
281 #endif