diff options
Diffstat (limited to 'src/assuan.h.in')
| -rw-r--r-- | src/assuan.h.in | 649 |
1 files changed, 649 insertions, 0 deletions
diff --git a/src/assuan.h.in b/src/assuan.h.in new file mode 100644 index 0000000..91b75ab --- /dev/null +++ b/src/assuan.h.in @@ -0,0 +1,649 @@ +/* assuan.h - Definitions for the Assuan IPC library -*- c -*- + Copyright (C) 2001, 2002, 2003, 2005, 2007, 2008, 2009, + 2010 Free Software Foundation, Inc. + + This file is part of Assuan. + + Assuan is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as + published by the Free Software Foundation; either version 2.1 of + the License, or (at your option) any later version. + + Assuan is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this program; if not, see <http://www.gnu.org/licenses/>. + + @configure_input@ + */ + +#ifndef ASSUAN_H +#define ASSUAN_H + +#include <stdio.h> +#include <sys/types.h> +#include <unistd.h> +#include <stdarg.h> + +#ifndef _ASSUAN_NO_SOCKET_WRAPPER +#ifdef _WIN32 +#include <ws2tcpip.h> +#else +#include <sys/socket.h> +#endif +#endif /*!_ASSUAN_NO_SOCKET_WRAPPER*/ + +#ifdef _WIN32 +typedef void *assuan_msghdr_t; +#else +typedef struct msghdr *assuan_msghdr_t; +#endif + +#include <gpg-error.h> + +/* Compile time configuration: + + #define _ASSUAN_NO_SOCKET_WRAPPER + + Do not include the definitions for the socket wrapper feature. */ + + +#ifdef __cplusplus +extern "C" +{ +#if 0 +} +#endif +#endif + + +/* Check for compiler features. */ +#if __GNUC__ +#define _ASSUAN_GCC_VERSION (__GNUC__ * 10000 \ + + __GNUC_MINOR__ * 100 \ + + __GNUC_PATCHLEVEL__) + +#if _ASSUAN_GCC_VERSION > 30100 +#define _ASSUAN_DEPRECATED __attribute__ ((__deprecated__)) +#endif +#endif +#ifndef _ASSUAN_DEPRECATED +#define _ASSUAN_DEPRECATED +#endif + + +#define ASSUAN_LINELENGTH 1002 /* 1000 + [CR,]LF */ + +struct assuan_context_s; +typedef struct assuan_context_s *assuan_context_t; + +/* Because we use system handles and not libc low level file + descriptors on W32, we need to declare them as HANDLE (which + actually is a plain pointer). This is required to eventually + support 64 bit Windows systems. */ +#ifdef _WIN32 +typedef void *assuan_fd_t; +#define ASSUAN_INVALID_FD ((void*)(-1)) +#define ASSUAN_INVALID_PID ((pid_t) -1) +static inline assuan_fd_t +assuan_fd_from_posix_fd (int fd) +{ +#ifdef __MINGW32CE__ + return (assuan_fd_t)(fd); +#else + if (fd < 0) + return ASSUAN_INVALID_FD; + else + return (assuan_fd_t) _get_osfhandle (fd); +#endif +} +#else +typedef int assuan_fd_t; +#define ASSUAN_INVALID_FD (-1) +#define ASSUAN_INVALID_PID ((pid_t) -1) +static inline assuan_fd_t +assuan_fd_from_posix_fd (int fd) +{ + return fd; +} +#endif + +assuan_fd_t assuan_fdopen (int fd); + + +/* Assuan features an emulation of Unix domain sockets based on a + local TCP connections. To implement access permissions based on + file permissions a nonce is used which is expected by the server as + the first bytes received. This structure is used by the server to + save the nonce created initially by bind. On POSIX systems this is + a dummy operation. */ +struct assuan_sock_nonce_s +{ + size_t length; +#ifdef _WIN32 + char nonce[16]; +#endif +}; +typedef struct assuan_sock_nonce_s assuan_sock_nonce_t; + +/* Define the Unix domain socket structure for Windows. */ +#if defined(_WIN32) && !defined(_ASSUAN_NO_SOCKET_WRAPPER) +#ifndef AF_LOCAL +#define AF_LOCAL AF_UNIX +#endif +#define EADDRINUSE WSAEADDRINUSE +struct sockaddr_un +{ + short sun_family; + unsigned short sun_port; + struct in_addr sun_addr; + char sun_path[108-2-4]; +}; +#endif + + +/* Global interface. */ + +struct assuan_malloc_hooks +{ + void *(*malloc) (size_t cnt); + void *(*realloc) (void *ptr, size_t cnt); + void (*free) (void *ptr); +}; +typedef struct assuan_malloc_hooks *assuan_malloc_hooks_t; + +/* Categories for log messages. */ +#define ASSUAN_LOG_INIT 1 +#define ASSUAN_LOG_CTX 2 +#define ASSUAN_LOG_ENGINE 3 +#define ASSUAN_LOG_DATA 4 +#define ASSUAN_LOG_SYSIO 5 +#define ASSUAN_LOG_CONTROL 8 + +/* If MSG is NULL, return true/false depending on if this category is + logged. This is used to probe before expensive log message + generation (buffer dumps). */ +typedef int (*assuan_log_cb_t) (assuan_context_t ctx, void *hook, + unsigned int cat, const char *msg); + +/* Set the default gpg error source. */ +void assuan_set_gpg_err_source (gpg_err_source_t errsource); + +/* Get the default gpg error source. */ +gpg_err_source_t assuan_get_gpg_err_source (void); + + +/* Set the default malloc hooks. */ +void assuan_set_malloc_hooks (assuan_malloc_hooks_t malloc_hooks); + +/* Get the default malloc hooks. */ +assuan_malloc_hooks_t assuan_get_malloc_hooks (void); + + +/* Set the default log callback handler. */ +void assuan_set_log_cb (assuan_log_cb_t log_cb, void *log_cb_data); + +/* Get the default log callback handler. */ +void assuan_get_log_cb (assuan_log_cb_t *log_cb, void **log_cb_data); + + +/* Create a new Assuan context. The initial parameters are all needed + in the creation of the context. */ +gpg_error_t assuan_new_ext (assuan_context_t *ctx, gpg_err_source_t errsource, + assuan_malloc_hooks_t malloc_hooks, + assuan_log_cb_t log_cb, void *log_cb_data); + +/* Create a new context with default arguments. */ +gpg_error_t assuan_new (assuan_context_t *ctx); + +/* Release all resources associated with the given context. */ +void assuan_release (assuan_context_t ctx); + +/* Release the memory at PTR using the allocation handler of the + context CTX. This is a convenience function. */ +void assuan_free (assuan_context_t ctx, void *ptr); + + +/* Set user-data in a context. */ +void assuan_set_pointer (assuan_context_t ctx, void *pointer); + +/* Get user-data in a context. */ +void *assuan_get_pointer (assuan_context_t ctx); + + +/* Definitions of flags for assuan_set_flag(). */ +typedef unsigned int assuan_flag_t; + +/* When using a pipe server, by default Assuan will wait for the + forked process to die in assuan_release. In certain cases this + is not desirable. By setting this flag, the waitpid will be + skipped and the caller is responsible to cleanup a forked + process. */ +#define ASSUAN_NO_WAITPID 1 +/* This flag indicates whether Assuan logging is in confidential mode. + You can use assuan_{begin,end}_condidential to change the mode. */ +#define ASSUAN_CONFIDENTIAL 2 +/* This flag suppresses fix up of signal handlers for pipes. */ +#define ASSUAN_NO_FIXSIGNALS 3 + +/* For context CTX, set the flag FLAG to VALUE. Values for flags + are usually 1 or 0 but certain flags might allow for other values; + see the description of the type assuan_flag_t for details. */ +void assuan_set_flag (assuan_context_t ctx, assuan_flag_t flag, int value); + +/* Return the VALUE of FLAG in context CTX. */ +int assuan_get_flag (assuan_context_t ctx, assuan_flag_t flag); + + +/* Same as assuan_set_flag (ctx, ASSUAN_CONFIDENTIAL, 1). */ +void assuan_begin_confidential (assuan_context_t ctx); + +/* Same as assuan_set_flag (ctx, ASSUAN_CONFIDENTIAL, 0). */ +void assuan_end_confidential (assuan_context_t ctx); + + +/* Direction values for assuan_set_io_monitor. */ +#define ASSUAN_IO_FROM_PEER 0 +#define ASSUAN_IO_TO_PEER 1 + +/* Return flags of I/O monitor. */ +#define ASSUAN_IO_MONITOR_NOLOG 1 +#define ASSUAN_IO_MONITOR_IGNORE 2 + +/* The IO monitor gets to see all I/O on the context, and can return + ASSUAN_IO_MONITOR_* bits to control actions on it. */ +typedef unsigned int (*assuan_io_monitor_t) (assuan_context_t ctx, void *hook, + int inout, const char *line, + size_t linelen); + +/* Set the IO monitor function. */ +void assuan_set_io_monitor (assuan_context_t ctx, + assuan_io_monitor_t io_monitor, void *hook_data); + + +#define ASSUAN_SYSTEM_HOOKS_VERSION 1 +#define ASSUAN_SPAWN_DETACHED 128 +struct assuan_system_hooks +{ + /* Always set to ASSUAN_SYTEM_HOOKS_VERSION. */ + int version; + + /* Sleep for the given number of microseconds. */ + void (*usleep) (assuan_context_t ctx, unsigned int usec); + + /* Create a pipe with an inheritable end. */ + int (*pipe) (assuan_context_t ctx, assuan_fd_t fd[2], int inherit_idx); + + /* Close the given file descriptor, created with _assuan_pipe or one + of the socket functions. */ + int (*close) (assuan_context_t ctx, assuan_fd_t fd); + + + ssize_t (*read) (assuan_context_t ctx, assuan_fd_t fd, void *buffer, + size_t size); + ssize_t (*write) (assuan_context_t ctx, assuan_fd_t fd, + const void *buffer, size_t size); + + int (*recvmsg) (assuan_context_t ctx, assuan_fd_t fd, assuan_msghdr_t msg, + int flags); + int (*sendmsg) (assuan_context_t ctx, assuan_fd_t fd, + const assuan_msghdr_t msg, int flags); + + /* If NAME is NULL, don't exec, just fork. FD_CHILD_LIST is + modified to reflect the value of the FD in the peer process (on + Windows). */ + int (*spawn) (assuan_context_t ctx, pid_t *r_pid, const char *name, + const char **argv, + assuan_fd_t fd_in, assuan_fd_t fd_out, + assuan_fd_t *fd_child_list, + void (*atfork) (void *opaque, int reserved), + void *atforkvalue, unsigned int flags); + + /* If action is 0, like waitpid. If action is 1, just release the PID? */ + pid_t (*waitpid) (assuan_context_t ctx, pid_t pid, + int action, int *status, int options); + int (*socketpair) (assuan_context_t ctx, int _namespace, int style, + int protocol, assuan_fd_t filedes[2]); +}; +typedef struct assuan_system_hooks *assuan_system_hooks_t; + + +/* Configuration of the default log handler. */ + +/* Set the prefix to be used at the start of a line emitted by assuan + on the log stream. The default is the empty string. Note, that + this function is not thread-safe and should in general be used + right at startup. */ +void assuan_set_assuan_log_prefix (const char *text); + +/* Return a prefix to be used at the start of a line emitted by assuan + on the log stream. The default implementation returns the empty + string, i.e. "" */ +const char *assuan_get_assuan_log_prefix (void); + +/* Global default log stream. */ +void assuan_set_assuan_log_stream (FILE *fp); + +/* Set the per context log stream for the default log handler. */ +void assuan_set_log_stream (assuan_context_t ctx, FILE *fp); + + +typedef gpg_error_t (*assuan_handler_t) (assuan_context_t, char *); + +/*-- assuan-handler.c --*/ +gpg_error_t assuan_register_command (assuan_context_t ctx, + const char *cmd_string, + assuan_handler_t handler, + const char *help_string); +gpg_error_t assuan_register_post_cmd_notify (assuan_context_t ctx, + void (*fnc)(assuan_context_t, + gpg_error_t)); +gpg_error_t assuan_register_bye_notify (assuan_context_t ctx, + assuan_handler_t handler); +gpg_error_t assuan_register_reset_notify (assuan_context_t ctx, + assuan_handler_t handler); +gpg_error_t assuan_register_cancel_notify (assuan_context_t ctx, + assuan_handler_t handler); +gpg_error_t assuan_register_input_notify (assuan_context_t ctx, + assuan_handler_t handler); +gpg_error_t assuan_register_output_notify (assuan_context_t ctx, + assuan_handler_t handler); + +gpg_error_t assuan_register_option_handler (assuan_context_t ctx, + gpg_error_t (*fnc)(assuan_context_t, + const char*, + const char*)); + +gpg_error_t assuan_process (assuan_context_t ctx); +gpg_error_t assuan_process_next (assuan_context_t ctx, int *done); +gpg_error_t assuan_process_done (assuan_context_t ctx, gpg_error_t rc); +int assuan_get_active_fds (assuan_context_t ctx, int what, + assuan_fd_t *fdarray, int fdarraysize); + +const char *assuan_get_command_name (assuan_context_t ctx); + +FILE *assuan_get_data_fp (assuan_context_t ctx); +gpg_error_t assuan_set_okay_line (assuan_context_t ctx, const char *line); +gpg_error_t assuan_write_status (assuan_context_t ctx, + const char *keyword, const char *text); + +/* Negotiate a file descriptor. If LINE contains "FD=N", returns N + assuming a local file descriptor. If LINE contains "FD" reads a + file descriptor via CTX and stores it in *RDF (the CTX must be + capable of passing file descriptors). Under W32 the returned FD is + a libc-type one. */ +gpg_error_t assuan_command_parse_fd (assuan_context_t ctx, char *line, + assuan_fd_t *rfd); + + +/*-- assuan-listen.c --*/ +gpg_error_t assuan_set_hello_line (assuan_context_t ctx, const char *line); +gpg_error_t assuan_accept (assuan_context_t ctx); +assuan_fd_t assuan_get_input_fd (assuan_context_t ctx); +assuan_fd_t assuan_get_output_fd (assuan_context_t ctx); +gpg_error_t assuan_close_input_fd (assuan_context_t ctx); +gpg_error_t assuan_close_output_fd (assuan_context_t ctx); + + +/*-- assuan-pipe-server.c --*/ +gpg_error_t assuan_init_pipe_server (assuan_context_t ctx, + assuan_fd_t filedes[2]); + +/*-- assuan-socket-server.c --*/ +#define ASSUAN_SOCKET_SERVER_FDPASSING 1 +#define ASSUAN_SOCKET_SERVER_ACCEPTED 2 +gpg_error_t assuan_init_socket_server (assuan_context_t ctx, + assuan_fd_t listen_fd, + unsigned int flags); +void assuan_set_sock_nonce (assuan_context_t ctx, assuan_sock_nonce_t *nonce); + +/*-- assuan-pipe-connect.c --*/ +#define ASSUAN_PIPE_CONNECT_FDPASSING 1 +#define ASSUAN_PIPE_CONNECT_DETACHED 128 +gpg_error_t assuan_pipe_connect (assuan_context_t ctx, + const char *name, + const char *argv[], + assuan_fd_t *fd_child_list, + void (*atfork) (void *, int), + void *atforkvalue, + unsigned int flags); + +/*-- assuan-socket-connect.c --*/ +#define ASSUAN_SOCKET_CONNECT_FDPASSING 1 +gpg_error_t assuan_socket_connect (assuan_context_t ctx, const char *name, + pid_t server_pid, unsigned int flags); + +/*-- assuan-connect.c --*/ +pid_t assuan_get_pid (assuan_context_t ctx); +struct _assuan_peercred +{ +#ifdef _WIN32 + /* Empty struct not allowed on some compilers. */ + unsigned int _dummy; +#else + pid_t pid; + uid_t uid; + gid_t gid; +#endif +}; +typedef struct _assuan_peercred *assuan_peercred_t; + +gpg_error_t assuan_get_peercred (assuan_context_t ctx, + assuan_peercred_t *peercred); + + + +/* Client interface. */ +#define ASSUAN_RESPONSE_ERROR 0 +#define ASSUAN_RESPONSE_OK 1 +#define ASSUAN_RESPONSE_DATA 2 +#define ASSUAN_RESPONSE_INQUIRE 3 +#define ASSUAN_RESPONSE_STATUS 4 +#define ASSUAN_RESPONSE_END 5 +#define ASSUAN_RESPONSE_COMMENT 6 +typedef int assuan_response_t; + +/* This already de-escapes data lines. */ +gpg_error_t assuan_client_read_response (assuan_context_t ctx, + char **line, int *linelen); + +gpg_error_t assuan_client_parse_response (assuan_context_t ctx, + char *line, int linelen, + assuan_response_t *response, + int *off); + +/*-- assuan-client.c --*/ +gpg_error_t +assuan_transact (assuan_context_t ctx, + const char *command, + gpg_error_t (*data_cb)(void *, const void *, size_t), + void *data_cb_arg, + gpg_error_t (*inquire_cb)(void*, const char *), + void *inquire_cb_arg, + gpg_error_t (*status_cb)(void*, const char *), + void *status_cb_arg); + + +/*-- assuan-inquire.c --*/ +gpg_error_t assuan_inquire (assuan_context_t ctx, const char *keyword, + unsigned char **r_buffer, size_t *r_length, + size_t maxlen); +gpg_error_t assuan_inquire_ext (assuan_context_t ctx, const char *keyword, + size_t maxlen, + gpg_error_t (*cb) (void *cb_data, + gpg_error_t rc, + unsigned char *buf, + size_t buf_len), + void *cb_data); +/*-- assuan-buffer.c --*/ +gpg_error_t assuan_read_line (assuan_context_t ctx, + char **line, size_t *linelen); +int assuan_pending_line (assuan_context_t ctx); +gpg_error_t assuan_write_line (assuan_context_t ctx, const char *line); +gpg_error_t assuan_send_data (assuan_context_t ctx, + const void *buffer, size_t length); + +/* The file descriptor must be pending before assuan_receivefd is + called. This means that assuan_sendfd should be called *before* the + trigger is sent (normally via assuan_write_line ("INPUT FD")). */ +gpg_error_t assuan_sendfd (assuan_context_t ctx, assuan_fd_t fd); +gpg_error_t assuan_receivefd (assuan_context_t ctx, assuan_fd_t *fd); + + +/*-- assuan-util.c --*/ +gpg_error_t assuan_set_error (assuan_context_t ctx, gpg_error_t err, + const char *text); + + + +/*-- assuan-socket.c --*/ + +/* These are socket wrapper functions to support an emulation of Unix + domain sockets on Windows W32. */ +gpg_error_t assuan_sock_init (void); +void assuan_sock_deinit (void); +int assuan_sock_close (assuan_fd_t fd); +assuan_fd_t assuan_sock_new (int domain, int type, int proto); +int assuan_sock_connect (assuan_fd_t sockfd, + struct sockaddr *addr, int addrlen); +int assuan_sock_bind (assuan_fd_t sockfd, struct sockaddr *addr, int addrlen); +int assuan_sock_get_nonce (struct sockaddr *addr, int addrlen, + assuan_sock_nonce_t *nonce); +int assuan_sock_check_nonce (assuan_fd_t fd, assuan_sock_nonce_t *nonce); + + +/* Set the default or per context system callbacks. This is + irreversible. */ +void assuan_set_system_hooks (assuan_system_hooks_t system_hooks); + +void assuan_ctx_set_system_hooks (assuan_context_t ctx, + assuan_system_hooks_t system_hooks); + +void __assuan_usleep (assuan_context_t ctx, unsigned int usec); +int __assuan_pipe (assuan_context_t ctx, assuan_fd_t fd[2], int inherit_idx); +int __assuan_close (assuan_context_t ctx, assuan_fd_t fd); +int __assuan_spawn (assuan_context_t ctx, pid_t *r_pid, const char *name, + const char **argv, assuan_fd_t fd_in, assuan_fd_t fd_out, + assuan_fd_t *fd_child_list, + void (*atfork) (void *opaque, int reserved), + void *atforkvalue, unsigned int flags); +int __assuan_socketpair (assuan_context_t ctx, int _namespace, int style, + int protocol, assuan_fd_t filedes[2]); + +#ifdef _WIN32 +#define _ASSUAN_SYSTEM_PTH_IMPL \ + static int _assuan_pth_recvmsg (assuan_context_t ctx, assuan_fd_t fd, \ + assuan_msghdr_t msg, int flags) \ + { \ + (void) ctx; \ + errno = ENOSYS; \ + return -1; \ + } \ + static int _assuan_pth_sendmsg (assuan_context_t ctx, assuan_fd_t fd, \ + const assuan_msghdr_t msg, int flags) \ + { \ + (void) ctx; \ + errno = ENOSYS; \ + return -1; \ + } +#else +#define _ASSUAN_SYSTEM_PTH_IMPL \ + static int _assuan_pth_recvmsg (assuan_context_t ctx, assuan_fd_t fd, \ + assuan_msghdr_t msg, int flags) \ + { \ + /* Pth does not provide a recvmsg function. We implement it. */ \ + int ret; \ + int fdmode; \ + \ + (void) ctx; \ + fdmode = pth_fdmode (fd, PTH_FDMODE_POLL); \ + if (fdmode == PTH_FDMODE_ERROR) \ + { \ + errno = EBADF; \ + return -1; \ + } \ + if (fdmode == PTH_FDMODE_BLOCK) \ + { \ + fd_set fds; \ + \ + FD_ZERO (&fds); \ + FD_SET (fd, &fds); \ + while ((ret = pth_select (fd + 1, &fds, NULL, NULL, NULL)) < 0 \ + && errno == EINTR) \ + ; \ + if (ret < 0) \ + return -1; \ + } \ + \ + while ((ret = recvmsg (fd, msg, flags)) == -1 && errno == EINTR) \ + ; \ + return ret; \ + } \ + static int _assuan_pth_sendmsg (assuan_context_t ctx, assuan_fd_t fd, \ + const assuan_msghdr_t msg, int flags) \ + { \ + /* Pth does not provide a sendmsg function. We implement it. */ \ + int ret; \ + int fdmode; \ + \ + (void) ctx; \ + fdmode = pth_fdmode (fd, PTH_FDMODE_POLL); \ + if (fdmode == PTH_FDMODE_ERROR) \ + { \ + errno = EBADF; \ + return -1; \ + } \ + if (fdmode == PTH_FDMODE_BLOCK) \ + { \ + fd_set fds; \ + \ + FD_ZERO (&fds); \ + FD_SET (fd, &fds); \ + while ((ret = pth_select (fd + 1, NULL, &fds, NULL, NULL)) < 0 \ + && errno == EINTR) \ + ; \ + if (ret < 0) \ + return -1; \ + } \ + \ + while ((ret = sendmsg (fd, msg, flags)) == -1 && errno == EINTR) \ + ; \ + return ret; \ + } +#endif + + +#define ASSUAN_SYSTEM_PTH_IMPL \ + static void _assuan_pth_usleep (assuan_context_t ctx, unsigned int usec) \ + { (void) ctx; pth_usleep (usec); } \ + static ssize_t _assuan_pth_read (assuan_context_t ctx, assuan_fd_t fd, \ + void *buffer, size_t size) \ + { (void) ctx; return pth_read (fd, buffer, size); } \ + static ssize_t _assuan_pth_write (assuan_context_t ctx, assuan_fd_t fd, \ + const void *buffer, size_t size) \ + { (void) ctx; return pth_write (fd, buffer, size); } \ + _ASSUAN_SYSTEM_PTH_IMPL \ + static pid_t _assuan_pth_waitpid (assuan_context_t ctx, pid_t pid, \ + int nowait, int *status, int options) \ + { (void) ctx; \ + if (!nowait) return pth_waitpid (pid, status, options); \ + else return 0; } \ + \ + struct assuan_system_hooks _assuan_system_pth = \ + { ASSUAN_SYSTEM_HOOKS_VERSION, _assuan_pth_usleep, __assuan_pipe, \ + __assuan_close, _assuan_pth_read, _assuan_pth_write, \ + _assuan_pth_recvmsg, _assuan_pth_sendmsg, \ + __assuan_spawn, _assuan_pth_waitpid, __assuan_socketpair } + +extern struct assuan_system_hooks _assuan_system_pth; +#define ASSUAN_SYSTEM_PTH &_assuan_system_pth + +@include:w32ce-add@ + +#ifdef __cplusplus +} +#endif +#endif /* ASSUAN_H */ |