2005-03-24 Marcus Brinkmann <marcus@g10code.de>
[gpgme.git] / assuan / assuan.h
1 /* assuan.c - Definitions for the Assuan protocol
2  *      Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc.
3  *
4  * This file is part of Assuan.
5  *
6  * Assuan is free software; you can redistribute it and/or modify it
7  * under the terms of the GNU Lesser General Public License as
8  * published by the Free Software Foundation; either version 2.1 of
9  * the License, or (at your option) any later version.
10  *
11  * Assuan is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA 
19  */
20
21 #ifndef ASSUAN_H
22 #define ASSUAN_H
23
24 #include <stdio.h>
25 #include <sys/types.h>
26 #include <unistd.h>
27
28 #include <sys/socket.h>
29
30 #define _ASSUAN_IN_GPGME
31 #ifdef _ASSUAN_IN_GPGME
32 #define _ASSUAN_EXT_SYM_PREFIX _gpgme_
33
34 #ifdef _ASSUAN_IN_GPGME_BUILD_ASSUAN
35 int _gpgme_io_read (int fd, void *buffer, size_t count);
36 int _gpgme_io_write (int fd, const void *buffer, size_t count);
37 ssize_t _gpgme_ath_select (int nfd, fd_set *rset, fd_set *wset, fd_set *eset,
38                            struct timeval *timeout);
39 ssize_t _gpgme_ath_waitpid (pid_t pid, int *status, int options);
40 int _gpgme_ath_accept (int s, struct sockaddr *addr, socklen_t *length_ptr);
41 int _gpgme_ath_connect (int s, struct sockaddr *addr, socklen_t length);
42 int _gpgme_ath_sendmsg (int s, const struct msghdr *msg, int flags);
43 int _gpgme_ath_recvmsg (int s, struct msghdr *msg, int flags);
44
45 #define read          _gpgme_io_read
46 #define write         _gpgme_io_write
47 #define waitpid       _gpgme_ath_waitpid
48 #define select        _gpgme_ath_select
49 #define accept        _gpgme_ath_accept
50 #define connect       _gpgme_ath_connect
51 #define sendmsg       _gpgme_ath_sendmsg
52 #define recvmsg       _gpgme_ath_recvmsg
53 #endif
54 #endif
55
56 #ifdef _ASSUAN_EXT_SYM_PREFIX
57 #define _ASSUAN_PREFIX1(x,y) x ## y
58 #define _ASSUAN_PREFIX2(x,y) _ASSUAN_PREFIX1(x,y)
59 #define _ASSUAN_PREFIX(x) _ASSUAN_PREFIX2(_ASSUAN_EXT_SYM_PREFIX,x)
60 #define assuan_ _ASSUAN_PREFIX(assuan_)
61 #define assuan_register_command _ASSUAN_PREFIX(assuan_register_command)
62 #define assuan_register_bye_notify _ASSUAN_PREFIX(assuan_register_bye_notify)
63 #define assuan_register_reset_notify \
64   _ASSUAN_PREFIX(assuan_register_reset_notify)
65 #define assuan_register_cancel_notify \
66   _ASSUAN_PREFIX(assuan_register_cancel_notify)
67 #define assuan_register_input_notify \
68   _ASSUAN_PREFIX(assuan_register_input_notify)
69 #define assuan_register_output_notify \
70   _ASSUAN_PREFIX(assuan_register_output_notify)
71 #define assuan_register_option_handler \
72   _ASSUAN_PREFIX(assuan_register_option_handler)
73 #define assuan_process _ASSUAN_PREFIX(assuan_process)
74 #define assuan_process_next _ASSUAN_PREFIX(assuan_process_next)
75 #define assuan_get_active_fds _ASSUAN_PREFIX(assuan_get_active_fds)
76 #define assuan_get_data_fp _ASSUAN_PREFIX(assuan_get_data_fp)
77 #define assuan_set_okay_line _ASSUAN_PREFIX(assuan_set_okay_line)
78 #define assuan_write_status _ASSUAN_PREFIX(assuan_write_status)
79 #define assuan_command_parse_fd _ASSUAN_PREFIX(assuan_command_parse_fd)
80 #define assuan_set_hello_line _ASSUAN_PREFIX(assuan_set_hello_line)
81 #define assuan_accept _ASSUAN_PREFIX(assuan_accept)
82 #define assuan_get_input_fd _ASSUAN_PREFIX(assuan_get_input_fd)
83 #define assuan_get_output_fd _ASSUAN_PREFIX(assuan_get_output_fd)
84 #define assuan_close_input_fd _ASSUAN_PREFIX(assuan_close_input_fd)
85 #define assuan_close_output_fd _ASSUAN_PREFIX(assuan_close_output_fd)
86 #define assuan_init_pipe_server _ASSUAN_PREFIX(assuan_init_pipe_server)
87 #define assuan_deinit_server _ASSUAN_PREFIX(assuan_deinit_server)
88 #define assuan_init_socket_server _ASSUAN_PREFIX(assuan_init_socket_server)
89 #define assuan_init_connected_socket_server \
90   _ASSUAN_PREFIX(assuan_init_connected_socket_server)
91 #define assuan_pipe_connect _ASSUAN_PREFIX(assuan_pipe_connect)
92 #define assuan_socket_connect _ASSUAN_PREFIX(assuan_socket_connect)
93 #define assuan_domain_connect _ASSUAN_PREFIX(assuan_domain_connect)
94 #define assuan_init_domain_server _ASSUAN_PREFIX(assuan_init_domain_server)
95 #define assuan_disconnect _ASSUAN_PREFIX(assuan_disconnect)
96 #define assuan_get_pid _ASSUAN_PREFIX(assuan_get_pid)
97 #define assuan_transact _ASSUAN_PREFIX(assuan_transact)
98 #define assuan_inquire _ASSUAN_PREFIX(assuan_inquire)
99 #define assuan_read_line _ASSUAN_PREFIX(assuan_read_line)
100 #define assuan_pending_line _ASSUAN_PREFIX(assuan_pending_line)
101 #define assuan_write_line _ASSUAN_PREFIX(assuan_write_line)
102 #define assuan_send_data _ASSUAN_PREFIX(assuan_send_data)
103 #define assuan_sendfd _ASSUAN_PREFIX(assuan_sendfd)
104 #define assuan_receivefd _ASSUAN_PREFIX(assuan_receivefd)
105 #define assuan_set_malloc_hooks _ASSUAN_PREFIX(assuan_set_malloc_hooks)
106 #define assuan_set_log_stream _ASSUAN_PREFIX(assuan_set_log_stream)
107 #define assuan_set_error _ASSUAN_PREFIX(assuan_set_error)
108 #define assuan_set_pointer _ASSUAN_PREFIX(assuan_set_pointer)
109 #define assuan_get_pointer _ASSUAN_PREFIX(assuan_get_pointer)
110 #define assuan_begin_confidential _ASSUAN_PREFIX(assuan_begin_confidential)
111 #define assuan_end_confidential _ASSUAN_PREFIX(assuan_end_confidential)
112 #define assuan_strerror _ASSUAN_PREFIX(assuan_strerror)
113 #define assuan_set_assuan_log_stream \
114   _ASSUAN_PREFIX(assuan_set_assuan_log_stream)
115 #define assuan_get_assuan_log_stream \
116   _ASSUAN_PREFIX(assuan_get_assuan_log_stream)
117 #define assuan_get_assuan_log_prefix \
118   _ASSUAN_PREFIX(assuan_get_assuan_log_prefix)
119
120 /* And now the internal functions, argh...  */
121 #define _assuan_read_line _ASSUAN_PREFIX(_assuan_read_line)
122 #define _assuan_cookie_write_data _ASSUAN_PREFIX(_assuan_cookie_write_data)
123 #define _assuan_cookie_write_flush _ASSUAN_PREFIX(_assuan_cookie_write_flush)
124 #define _assuan_read_from_server _ASSUAN_PREFIX(_assuan_read_from_server)
125 #define _assuan_domain_init _ASSUAN_PREFIX(_assuan_domain_init)
126 #define _assuan_register_std_commands \
127   _ASSUAN_PREFIX(_assuan_register_std_commands)
128 #define _assuan_simple_read _ASSUAN_PREFIX(_assuan_simple_read)
129 #define _assuan_simple_write _ASSUAN_PREFIX(_assuan_simple_write)
130 #define _assuan_simple_read _ASSUAN_PREFIX(_assuan_simple_read)
131 #define _assuan_simple_write _ASSUAN_PREFIX(_assuan_simple_write)
132 #define _assuan_new_context _ASSUAN_PREFIX(_assuan_new_context)
133 #define _assuan_release_context _ASSUAN_PREFIX(_assuan_release_context)
134 #define _assuan_malloc _ASSUAN_PREFIX(_assuan_malloc)
135 #define _assuan_realloc _ASSUAN_PREFIX(_assuan_realloc)
136 #define _assuan_calloc _ASSUAN_PREFIX(_assuan_calloc)
137 #define _assuan_free _ASSUAN_PREFIX(_assuan_free)
138 #define _assuan_log_print_buffer _ASSUAN_PREFIX(_assuan_log_print_buffer)
139 #define _assuan_log_sanitized_string \
140   _ASSUAN_PREFIX(_assuan_log_sanitized_string)
141
142 #endif
143
144 #ifdef __cplusplus
145 extern "C"
146 {
147 #endif
148   
149
150 typedef enum
151 {
152   ASSUAN_No_Error = 0,
153   ASSUAN_General_Error = 1,
154   ASSUAN_Out_Of_Core = 2,
155   ASSUAN_Invalid_Value = 3,
156   ASSUAN_Timeout = 4,
157   ASSUAN_Read_Error = 5,
158   ASSUAN_Write_Error = 6,
159   ASSUAN_Problem_Starting_Server = 7,
160   ASSUAN_Not_A_Server = 8,
161   ASSUAN_Not_A_Client = 9,
162   ASSUAN_Nested_Commands = 10,
163   ASSUAN_Invalid_Response = 11,
164   ASSUAN_No_Data_Callback = 12,
165   ASSUAN_No_Inquire_Callback = 13,
166   ASSUAN_Connect_Failed = 14,
167   ASSUAN_Accept_Failed = 15,
168
169   /* error codes above 99 are meant as status codes */
170   ASSUAN_Not_Implemented = 100,
171   ASSUAN_Server_Fault    = 101,
172   ASSUAN_Invalid_Command = 102,
173   ASSUAN_Unknown_Command = 103,
174   ASSUAN_Syntax_Error    = 104,
175   ASSUAN_Parameter_Error = 105,
176   ASSUAN_Parameter_Conflict = 106,
177   ASSUAN_Line_Too_Long = 107,
178   ASSUAN_Line_Not_Terminated = 108,
179   ASSUAN_No_Input = 109,
180   ASSUAN_No_Output = 110,
181   ASSUAN_Canceled = 111,
182   ASSUAN_Unsupported_Algorithm = 112,
183   ASSUAN_Server_Resource_Problem = 113,
184   ASSUAN_Server_IO_Error = 114,
185   ASSUAN_Server_Bug = 115,
186   ASSUAN_No_Data_Available = 116,
187   ASSUAN_Invalid_Data = 117,
188   ASSUAN_Unexpected_Command = 118,
189   ASSUAN_Too_Much_Data = 119,
190   ASSUAN_Inquire_Unknown = 120,
191   ASSUAN_Inquire_Error = 121,
192   ASSUAN_Invalid_Option = 122,
193   ASSUAN_Invalid_Index = 123,
194   ASSUAN_Unexpected_Status = 124,
195   ASSUAN_Unexpected_Data = 125,
196   ASSUAN_Invalid_Status = 126,
197
198   ASSUAN_Not_Confirmed = 128,
199
200   ASSUAN_Bad_Certificate = 201,
201   ASSUAN_Bad_Certificate_Chain = 202,
202   ASSUAN_Missing_Certificate = 203,
203   ASSUAN_Bad_Signature = 204,
204   ASSUAN_No_Agent = 205,
205   ASSUAN_Agent_Error = 206,
206   ASSUAN_No_Public_Key = 207,
207   ASSUAN_No_Secret_Key = 208,
208   ASSUAN_Invalid_Name = 209,
209
210   ASSUAN_Cert_Revoked = 301,
211   ASSUAN_No_CRL_For_Cert = 302,
212   ASSUAN_CRL_Too_Old = 303,
213   ASSUAN_Not_Trusted = 304,
214
215   ASSUAN_Card_Error = 401,
216   ASSUAN_Invalid_Card = 402,
217   ASSUAN_No_PKCS15_App = 403,
218   ASSUAN_Card_Not_Present = 404,
219   ASSUAN_Invalid_Id = 405
220
221 } AssuanError;
222
223 /* This is a list of pre-registered ASSUAN commands */
224 typedef enum
225 {
226   ASSUAN_CMD_NOP = 0,
227   ASSUAN_CMD_CANCEL,    /* cancel the current request */
228   ASSUAN_CMD_BYE,
229   ASSUAN_CMD_AUTH,
230   ASSUAN_CMD_RESET,
231   ASSUAN_CMD_OPTION,
232   ASSUAN_CMD_DATA,
233   ASSUAN_CMD_END,
234   ASSUAN_CMD_INPUT,
235   ASSUAN_CMD_OUTPUT,
236
237   ASSUAN_CMD_USER = 256  /* Other commands should be used with this offset*/
238 } AssuanCommand;
239
240 #define ASSUAN_LINELENGTH 1002 /* 1000 + [CR,]LF */
241
242 struct assuan_context_s;
243 typedef struct assuan_context_s *ASSUAN_CONTEXT;
244
245 /*-- assuan-handler.c --*/
246 int assuan_register_command (ASSUAN_CONTEXT ctx,
247                              const char *cmd_string,
248                              int (*handler)(ASSUAN_CONTEXT, char *));
249 int assuan_register_bye_notify (ASSUAN_CONTEXT ctx,
250                                 void (*fnc)(ASSUAN_CONTEXT));
251 int assuan_register_reset_notify (ASSUAN_CONTEXT ctx,
252                                   void (*fnc)(ASSUAN_CONTEXT));
253 int assuan_register_cancel_notify (ASSUAN_CONTEXT ctx,
254                                    void (*fnc)(ASSUAN_CONTEXT));
255 int assuan_register_input_notify (ASSUAN_CONTEXT ctx,
256                                   void (*fnc)(ASSUAN_CONTEXT, const char *));
257 int assuan_register_output_notify (ASSUAN_CONTEXT ctx,
258                                   void (*fnc)(ASSUAN_CONTEXT, const char *));
259
260 int assuan_register_option_handler (ASSUAN_CONTEXT ctx,
261                                     int (*fnc)(ASSUAN_CONTEXT,
262                                                const char*, const char*));
263
264 int assuan_process (ASSUAN_CONTEXT ctx);
265 int assuan_process_next (ASSUAN_CONTEXT ctx);
266 int assuan_get_active_fds (ASSUAN_CONTEXT ctx, int what,
267                            int *fdarray, int fdarraysize);
268
269
270 FILE *assuan_get_data_fp (ASSUAN_CONTEXT ctx);
271 AssuanError assuan_set_okay_line (ASSUAN_CONTEXT ctx, const char *line);
272 void assuan_write_status (ASSUAN_CONTEXT ctx,
273                           const char *keyword, const char *text);
274
275 /* Negotiate a file descriptor.  If LINE contains "FD=N", returns N
276    assuming a local file descriptor.  If LINE contains "FD" reads a
277    file descriptor via CTX and stores it in *RDF (the CTX must be
278    capable of passing file descriptors).  */
279 AssuanError assuan_command_parse_fd (ASSUAN_CONTEXT ctx, char *line,
280                                      int *rfd);
281
282 /*-- assuan-listen.c --*/
283 AssuanError assuan_set_hello_line (ASSUAN_CONTEXT ctx, const char *line);
284 AssuanError assuan_accept (ASSUAN_CONTEXT ctx);
285 int assuan_get_input_fd (ASSUAN_CONTEXT ctx);
286 int assuan_get_output_fd (ASSUAN_CONTEXT ctx);
287 AssuanError assuan_close_input_fd (ASSUAN_CONTEXT ctx);
288 AssuanError assuan_close_output_fd (ASSUAN_CONTEXT ctx);
289
290
291 /*-- assuan-pipe-server.c --*/
292 int assuan_init_pipe_server (ASSUAN_CONTEXT *r_ctx, int filedes[2]);
293 void assuan_deinit_server (ASSUAN_CONTEXT ctx);
294
295 /*-- assuan-socket-server.c --*/
296 int assuan_init_socket_server (ASSUAN_CONTEXT *r_ctx, int listen_fd);
297 int assuan_init_connected_socket_server (ASSUAN_CONTEXT *r_ctx, int fd);
298
299
300 /*-- assuan-pipe-connect.c --*/
301 AssuanError assuan_pipe_connect (ASSUAN_CONTEXT *ctx, const char *name,
302                                  char *const argv[], int *fd_child_list);
303 /*-- assuan-socket-connect.c --*/
304 AssuanError assuan_socket_connect (ASSUAN_CONTEXT *ctx, const char *name,
305                                    pid_t server_pid);
306
307 /*-- assuan-domain-connect.c --*/
308
309 /* Connect to a Unix domain socket server.  RENDEZVOUSFD is
310    bidirectional file descriptor (normally returned via socketpair)
311    which the client can use to rendezvous with the server.  SERVER s
312    the server's pid.  */
313 AssuanError assuan_domain_connect (ASSUAN_CONTEXT *r_ctx,
314                                    int rendezvousfd,
315                                    pid_t server);
316
317 /*-- assuan-domain-server.c --*/
318
319 /* RENDEZVOUSFD is a bidirectional file descriptor (normally returned
320    via socketpair) that the domain server can use to rendezvous with
321    the client.  CLIENT is the client's pid.  */
322 AssuanError assuan_init_domain_server (ASSUAN_CONTEXT *r_ctx,
323                                        int rendezvousfd,
324                                        pid_t client);
325
326
327 /*-- assuan-connect.c --*/
328 void assuan_disconnect (ASSUAN_CONTEXT ctx);
329 pid_t assuan_get_pid (ASSUAN_CONTEXT ctx);
330
331 /*-- assuan-client.c --*/
332 AssuanError 
333 assuan_transact (ASSUAN_CONTEXT ctx,
334                  const char *command,
335                  AssuanError (*data_cb)(void *, const void *, size_t),
336                  void *data_cb_arg,
337                  AssuanError (*inquire_cb)(void*, const char *),
338                  void *inquire_cb_arg,
339                  AssuanError (*status_cb)(void*, const char *),
340                  void *status_cb_arg);
341
342
343 /*-- assuan-inquire.c --*/
344 AssuanError assuan_inquire (ASSUAN_CONTEXT ctx, const char *keyword,
345                             char **r_buffer, size_t *r_length, size_t maxlen);
346
347 /*-- assuan-buffer.c --*/
348 AssuanError assuan_read_line (ASSUAN_CONTEXT ctx,
349                               char **line, size_t *linelen);
350 int assuan_pending_line (ASSUAN_CONTEXT ctx);
351 AssuanError assuan_write_line (ASSUAN_CONTEXT ctx, const char *line );
352 AssuanError assuan_send_data (ASSUAN_CONTEXT ctx,
353                               const void *buffer, size_t length);
354
355 /* The file descriptor must be pending before assuan_receivefd is
356    call.  This means that assuan_sendfd should be called *before* the
357    trigger is sent (normally via assuan_send_data ("I sent you a
358    descriptor")).  */
359 AssuanError assuan_sendfd (ASSUAN_CONTEXT ctx, int fd);
360 AssuanError assuan_receivefd (ASSUAN_CONTEXT ctx, int *fd);
361
362 /*-- assuan-util.c --*/
363 void assuan_set_malloc_hooks ( void *(*new_alloc_func)(size_t n),
364                                void *(*new_realloc_func)(void *p, size_t n),
365                                void (*new_free_func)(void*) );
366 void assuan_set_log_stream (ASSUAN_CONTEXT ctx, FILE *fp);
367 int assuan_set_error (ASSUAN_CONTEXT ctx, int err, const char *text);
368 void assuan_set_pointer (ASSUAN_CONTEXT ctx, void *pointer);
369 void *assuan_get_pointer (ASSUAN_CONTEXT ctx);
370
371 void assuan_begin_confidential (ASSUAN_CONTEXT ctx);
372 void assuan_end_confidential (ASSUAN_CONTEXT ctx);
373
374 /*-- assuan-errors.c (built) --*/
375 const char *assuan_strerror (AssuanError err);
376
377 /*-- assuan-logging.c --*/
378
379 /* Set the stream to which assuan should log.  By default, this is
380    stderr.  */
381 extern void assuan_set_assuan_log_stream (FILE *fp);
382
383 /* Return the stream which is currently being using for logging.  */
384 extern FILE *assuan_get_assuan_log_stream (void);
385
386 /* User defined call back.  Return a prefix to be used at the start of
387    a line emitted by assuan on the log stream.  The default
388    implementation returns the empty string, i.e. ""  */
389 extern const char *assuan_get_assuan_log_prefix (void);
390
391 #ifdef __cplusplus
392 }
393 #endif
394 #endif /* ASSUAN_H */