assuan.texi
No OneTemporary
Actions

Size

31 KB

Subscribers

None

assuan.texi
View Options

	\input texinfo @c --texinfo--
	@c %**start of header
	@setfilename assuan.info

	@macro copyrightnotice
	Copyright @copyright{} 2002, 2003, 2006 Free Software Foundation, Inc.
	@end macro
	@macro permissionnotice
	Permission is granted to copy, distribute and/or modify this document
	under the terms of the GNU General Public License as published by the
	Free Software Foundation; either version 2 of the License, or (at your
	option) any later version. The text of the license can be found in the
	section entitled ``Copying''.
	@end macro

	@include version.texi

	@settitle Developing with Assuan

	@c Create a separate index for command line options.
	@defcodeindex op
	@c Merge the standard indexes into a single one.
	@syncodeindex fn cp
	@syncodeindex vr cp
	@syncodeindex ky cp
	@syncodeindex pg cp
	@syncodeindex tp cp

	@c A simple macro for optional variables.
	@macro ovar{varname}
	@r{[}@var{\varname\}@r{]}
	@end macro

	@c printing stuff taken from gcc.
	@macro gnupgtabopt{body}
	@code{\body\}
	@end macro
	@macro gnupgoptlist{body}
	@smallexample
	\body\
	@end smallexample
	@end macro
	@c Makeinfo handles the above macro OK, TeX needs manual line breaks;
	@c they get lost at some point in handling the macro. But if @macro is
	@c used here rather than @alias, it produces double line breaks.
	@iftex
	@alias gol = *
	@end iftex
	@ifnottex
	@macro gol
	@end macro
	@end ifnottex


	@c Change the font used for @def... commands, since the default
	@c proportional one used is bad for names starting __.
	@tex
	\global\setfont\defbf\ttbshape{10}{\magstep1}
	@end tex

	@c %**end of header

	@ifnottex
	@dircategory GNU Libraries
	@direntry
	* Assuan: (assuan). An IPC library for non-persistent servers.
	@end direntry
	This file documents the use and the internals of Assuan.

	This is Edition @value{EDITION}, last updated @value{UPDATED}, of
	@cite{The `Developing with Assuan' Manual}, for Version @value{VERSION}.
	@sp 1
	Published by the Free Software Foundation@*
	51 Franklin Street, Fifth Floor@*
	Boston, MA 02110-1301 USA
	@sp 1
	@copyrightnotice{}
	@sp 1
	@permissionnotice{}
	@end ifnottex

	@setchapternewpage odd

	@titlepage
	@title Developing with Assuan
	@subtitle Version @value{VERSION}
	@subtitle @value{UPDATED}
	@author Werner Koch @code{(wk@@gnupg.org)}

	@page
	@vskip 0pt plus 1filll
	@copyrightnotice{}
	@sp 2
	@permissionnotice{}
	@end titlepage
	@summarycontents
	@contents
	@page


	@ifnottex
	@node Top
	@top Introduction
	@cindex introduction

	This manual documents how to exploit the Assuan library, a simple
	interprocess communcation library.
	@end ifnottex

	@menu
	* Introduction:: An introduction to and the motivation behind Assuan.
	* Assuan:: Description of the Assuan protocol.
	* Implementation:: Overview of the implementation.
	* Preparation:: What you should do before using the library.
	* Generalities:: Initialization code and data types used.
	* Client code:: How to develop an Assuan client.
	* Server code:: How to develop an Assuan server.
	* Utilities:: Utility functions.

	Miscellaneous

	* Library Copying:: GNU Lesser General Public License says
	how you can copy and share Assuan.
	* Copying:: How you can copy and share this manual.

	Indices

	* Index:: Index of concepts and symbol names.

	@end menu


	@c
	@c I N T R O
	@c
	@node Introduction
	@chapter Introduction to Assuan

	In an ideal world, Assuan is irrelevant. Assuan's primary use is to
	allow a client to interact with a non-persistent server. Using
	Assuan, this is accomplished by forking a subprocess and communicating
	with it via, for example, a pipe or unix domain socket. This method
	is neither elegant nor efficient especially when there is a lot of
	data spread across several transactions: not only is there a penalty
	for an increased number of context switches, but also a significant
	amount of data is @var{memcpy}ed from the client to a file descriptor
	and from the file descriptor to the server. Despite these and other
	disadvantages, this type of client/server communication can be useful:
	the client is completely separate from the server; they are in
	different address spaces. This is especially important in situations
	where the server must have a known degree of reliability and data must
	be protected: as the Assuan protocol is well defined and clients
	cannot corrupt the servers' address space, auditing become much
	easier.

	Assuan was developed for use by the GNU Privacy Guard, GnuPG, to
	prevent potentially buggy clients from unwittingly corrupting
	sensitive transactions or compromising data such as a secret key.
	Assuan permits the servers, which do the actual work, e.g. encryption
	and decryption of data using a secret key, to be developed
	independently of the user interfaces, e.g. mail clients and other
	encryption front ends. Like a shared library, the interface is well
	defined and any number of front ends can use it; however, unlike a
	shared library, the client cannot see or touch the server's data. As
	with any modular system, Assuan helps keep the servers small and
	understandable help to make code more understandable and less error
	prone.

	Assuan is not, however, limited to use with GnuPG servers and clients:
	it was design to be flexible enough to meet the demands of almost any
	transaction based environment with non-persistent servers.

	@node Assuan
	@chapter Description of the Assuan protocol.

	The architecture of the modular GnuPG system is based on several
	highly specialized modules which compose a network of client/server
	communication. A common framework for intermodule communication is
	therefore needed and should be implemented in a library.

	Goals:

	@itemize @bullet
	@item Common framework for module communication
	@item Easy debugging
	@item Easy module testing
	@item Extendible
	@item Optional authentication and encryption facility
	@item Usable to access external hardware
	@end itemize


	Design criteria:

	@itemize @bullet
	@item Client server with back channel
	@item Use a mainly text based protocol
	@item Escape certain control characters
	@item Allow indefinite data length
	@item Request confidentiality for parts of the communication
	@item Dummy module to allow direct linking of client and server
	@item Inline data or descriptor passing for bulk data
	@item No protection against DoS needed
	@item Subliminal channels are not an issue
	@end itemize

	@node Implementation
	@chapter Implementation

	The implementation is line based with a maximum line size of 1000
	octects. The default IPC mechanism are Unix Domain Sockets.

	On a connect request the server responds either with an okay or an error
	status. For authentication check the server may send an Inquiry
	Response prior to the first Okay, it may also issue Status messages.
	The server must check that the client is allowed to connect, this is
	done by requesting the credentials for the peer and comparing them to
	those of the server. This avoids attacks based on wrong socket
	permissions.

	It may choose to delay the first response in case of an error. The
	server never closes the connection - however the lower protocol may do
	so after some time of inactivity or when the connection is in an error
	state.

	All textual messages are assumed to be in UTF-8 unless otherwise noted.


	@menu
	* Server responses:: Description of server responses.
	* Client requests:: Description of client requests.
	* Error codes:: List of error and status codes.
	@end menu


	@node Server responses
	@section Server responses

	@table @code
	@item OK [<arbitary debugging information>]
	Request was successful.

	@item ERR @var{errorcode} [<human readable error description>]
	Request could not be fulfilled. The error codes are mostly application
	specific except for a few common ones.

	@item S @var{keyword} <status information depending on keyword>
	Informational output by the server, still processing the request.

	@item # <string>
	Comment line issued only for debugging purposes. Totally ignored.

	@item D <raw data>
	Raw data returned to client. There must be exactly one space after the
	'D'. The values for '%', CR and LF must be percent escaped; this is
	encoded as %25, %0D and %0A. Only uppercase letters should be used in
	the hexadecimal representation. Other characters may be percent escaped
	for easier debugging. All these Data lines are considered one data
	stream up to the OK or ERR response. Status and Inquiry Responses
	may be mixed with the Data lines.

	@item INQUIRE @var{keyword}> <parameters>
	Server needs further information from the client. The client should
	answer with a command which is allowed after an inquiry. Note that the
	server does not confirm that client command but either continues
	processing or ends processing with an error status. Not all commands
	are allowed.
	@end table


	A client should only check the first letter of each line and then skip
	over to the next token (except for data lines where the raw data starts
	exactly after 2 bytes). Lines larger than 1000 bytes should be
	treated as a communication error. (The rationale for having a line
	length limit is to allow for easier multiplexing of several channels).


	@node Client requests
	@section Client requests

	The server waits for client requests after he sent an Okay or Error.
	The client should not issue a request in other cases.

	@example
	@var{command} <parameters>
	@end example

	@var{command} is a one word string without preceding white space.
	Parameters are command specific, CR, LF and the percent signs should be
	percent escaped as described above. To send a backslash as the last
	character it should also be percent escaped. Percent escaping is
	allowed anywhere in the parameters but not in the command. The line
	ends with a CR, LF or just a LF.

	Not yet implemented feature: If there is a need for a parameter list
	longer than the line length limit (1000 characters including command and
	CR, LF), the last character of the line (right before the CR/LF or LF)
	must be a non-escape encoded backslash. The following line is then
	expected to be a continuation of the line with the backslash replaced by
	a blank and the line ending removed.

	@example
	D <raw data>
	@end example

	Raw data to the server. There must be exactly one space after the 'D'.
	The values for '%', CR and LF must be percent escaped; this is encoded
	as %25, %0D and %0A. Only uppercase letters should be used in the
	hexadecimal representation. Other characters may be percent escaped for
	easier debugging. All these Data lines are considered one data stream
	up to the OKAY or ERROR response. Status and Inquiry Responses may be
	mixed with the Data lines.

	@example
	END
	@end example



	Lines beginning with a @code{#} or empty lines are ignored. This is
	useful to comment test scripts.


	Although the commands are application specific, some of them are used by
	all protocols and partly directly supported by the Assuan library:

	@table @code
	@item CANCEL
	This command is used for future extenxions. It may today be used to
	cancel outstanding requests in an asynchronous protocol.

	@item BYE
	Close the connect, the server will reply with an @code{OK}.

	@item AUTH
	Not yet specified as we don't implement it in the first phase. See my
	mail to gpa-dev on 2001-10-25 about the rationale for measurements
	against local attacks.

	@item RESET
	Reset the connection but not any existing authentication. The server
	should release all resources associated with the connection.

	@item END
	Used by a client to mark the end of raw data. The server may send END
	to indicate a partial end of data.

	@item HELP
	Reserved for future extensions.

	@item QUIT
	Reserved for future extensions.

	@end table


	@node Error codes
	@section Error codes

	Here we keep a list of error codes used in any Assuan based
	protocol. The format is the string @code{ERR}, white space, the error
	number, white space, a textual description of the error.

	General error codes pertaining to the actual Assuan operations:

	@table @code
	@item 0 Success
	@item 1 General error
	@item 2 Out of core
	@item 3 Invalid value
	@item 4 Timeout
	@item 5 Read error
	@item 6 Write error
	@item 7 Problem starting server
	@item 8 Not a server
	@item 9 Not a client
	@item 10 Nested commands
	@item 11 Invalid response
	@item 12 No data callback
	@item 13 No inquire callback
	@item 14 Connect failed
	@item 15 Accept failed
	@end table

	Error codes used as status codes in the Assuan protocol:

	@table @code
	@item 100 Not implemented
	@item 101 Server fault (catch all error code)
	@item 102 Invalid command
	@item 103 Unknown command
	@item 104 Syntax error
	@item 105 Parameter error
	@item 106 Parameter conflict
	@item 107 Line too long
	@item 108 Line not terminated
	@item 109 No input
	@item 110 No output
	@item 111 Canceled
	@item 112 Unsupported algorithm
	@item 113 Server resource problem
	@item 114 Server I/O error
	@item 115 Server bug
	@item 116 No data available
	@item 117 Invalid data
	@item 118 Unexpected command
	@item 119 Too much data
	@item 120 Inquire unknown
	@item 121 Inquire error
	@item 122 Invalid option
	@item 123 Invalid index
	@item 124 Unexpected status
	@item 125 Unexpected data
	@item 126 Invalid status
	@item 128 Not confirmed
	@end table

	For historical reasons a few more error codes are defined in
	@file{assuan.h}; they should not be used by new applications.

	Errror codes in the range @var{ASSUAN_USER_ERROR_FIRST} to
	@var{ASSUAN_USER_ERROR_LAST} may be used at the applications own
	discretion. Error codes greater than 65535 are not defined by Assuan
	and may also be used by applications --- note that the GnuPG system
	maps libgpg-error codes into this range.


	@c
	@c P R E P A R A T I O N
	@c
	@node Preparation
	@chapter Preparation

	To use `@sc{libassuan}', you have to perform some changes to your
	sources and the build system. The necessary changes are small and
	explained in the following sections.


	@menu
	* Header:: What header file you need to include.
	* Building sources:: How to build sources using the library.
	* Automake:: How to build sources with the help of Automake.
	* Multi Threading:: How @sc{libassuan} can be used in a MT environment.
	@end menu

	@node Header
	@section Header

	All interfaces (data types and functions) of @sc{libassuan} are defined
	in the header file @file{assuan.h}. You must include this in all source
	files using the library, either directly or through some other header
	file, like this:

	@example
	#include <assuan.h>
	@end example

	The name space of `@sc{assuan}' is @code{assuan_*} for function
	and type names and @code{ASSUAN*} for other symbols. In addition the
	same name prefixes with one prepended underscore are reserved for
	internal use and should never be used by an application.

	@node Building sources
	@section Building sources

	If you want to compile a source file including the @file{assuan.h}
	header file, you must make sure that the compiler can find it in the
	directory hierarchy. This is accomplished by adding the path to the
	directory in which the header file is located to the compilers include
	file search path (via the @option{-I} option).

	However, the path to the include file is determined at the time the
	source is configured. To solve this problem, @sc{libgcrypt} ships with
	a small helper program @command{libassuan-config} that knows the path to
	the include file and other configuration options. The options that need
	to be added to the compiler invocation at compile time are output by the
	@option{--cflags} option to @command{libassuan-config}. The following
	example shows how it can be used at the command line:

	@example
	gcc -c foo.c $(libassuan-config --cflags)
	@end example

	Adding the output of @samp{libassuan-config --cflags} to the compiler's
	command line will ensure that the compiler can find the @file{assuan.h}
	header file.

	A similar problem occurs when linking the program with the library.
	Again, the compiler/linker has to find the library files. For this to
	work, the path to the library files has to be added to the library
	search path (via the @option{-L} option). For this, the option
	@option{--libs} to @command{libassuan-config} can be used. For
	convenience, this option also outputs all other options that are
	required to link the program with the @sc{libassuan} libraries (in
	particular, the @option{-lassuan} option). The example shows how to
	link @file{foo.o} with the @sc{libassuan} library to a program
	@command{foo}.

	@example
	gcc -o foo foo.o $(libassuan-config --libs)
	@end example

	Of course you can also combine both examples to a single command by
	specifying both options to @command{libassuan-config}:

	@example
	gcc -o foo foo.c $(libassuan-config --cflags --libs)
	@end example

	@node Automake
	@section Building sources using Automake

	It is much easier if you use GNU Automake instead of writing your own
	Makefiles. If you do that you do not have to worry about finding and
	invoking the @command{libassuan-config} script at all. @sc{libassuan}
	provides an Automake macro that does all the work for you.

	@defmac AM_PATH_LIBASSUAN (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
	Check whether @sc{libassuan} (at least version @var{minimum-version}, if
	given) exists on the host system. If it is found, execute
	@var{action-if-found}, otherwise do @var{action-if-not-found}, if given.

	Additionally, the function defines @code{LIBASSUAN_CFLAGS} to the
	flags needed for compilation of the program to find the
	@file{assuan.h} header file, and @code{LIBASSUAN_LIBS} to the linker
	flags needed to link the program to the @sc{libassuan} library.
	@end defmac

	You can use the defined Autoconf variables like this in your
	@file{Makefile.am}:

	@example
	AM_CPPFLAGS = $(LIBASSUAN_CFLAGS)
	LDADD = $(LIBASSUAN_LIBS)
	@end example


	@node Multi Threading
	@section Multi Threading

	The @sc{libgcrypt} library is thread-safe if you adhere to the following
	requirements:

	@itemize @bullet
	@item Run the initialization functions before you actually start
	to use threads.
	@item Only one thread at a time may access an @sc{libassuan} context.
	@item Use @code{assuan_set_assuan_log_stream} to setup a default log stream.
	@end itemize


	@c
	@c G E N E R A L I T I E S
	@c
	@node Generalities
	@chapter Generalities

	@menu
	* Data Types:: Data types used by @sc{libassuan}.
	* Initializing the library:: How to initialize the library.
	* Reading and Writing:: How to communicate with the peer.
	@end menu



	@node Data Types
	@section Data Types used by the library

	@sc{libassuan} uses a context approach to keep state. The following
	data type is used all over the place:

	@deftp {Data type} assuan_context_t
	The @code{assuan_context_t} type is a pointer to an object mainted
	internally by the library. Certain Assuan functions allocate such a
	context and return it to the caller using this data type. Other
	functions take this data type to access the state created by these
	functions.
	@end deftp

	@noindent
	For compatibility with older versions of @sc{libassuan} a data
	type for error return values exists:

	@deftp {Data type} assuan_error_t
	This has orginally been an @code{enum} but applications should either
	view it as an @code{int} or if possible use the @code{gpg_error_t} data
	type as defined by the @sc{libgpg-error} package.
	@end deftp


	@node Initializing the library
	@section Initializing the library

	In general the library requires no initialization. There are however
	some initialization hooks provided which aren often useful. These
	should be called as early as possible and in a multi-threaded
	application before a second thread is created.

	If your application uses its own memory allocation functions or wrappers
	it is good idea to tell @sc{libassuan} about it so it can make use of the
	same functions or wrappers. You do this with

	@deftypefun void assuan_set_malloc_hooks (@w{void (@var{malloc_func})(size_t)}, @w{void (@var{realloc_func})(void , size_t)}, @w{void (@var{free_func})(void*)})
	You need to provide all three functions. Those functions need to behave
	exactly as their standard counterparts (@code{malloc}, @code{realloc}
	and @code{free}). If you write your own functions please take care to
	set @code{errno} whenever an error has occured.
	@end deftypefun

	@noindent
	To integrate assuan logging and diagnostics into your own logging
	system, you may use the following two functions:

	@deftypefun void assuan_set_assuan_log_stream (FILE *@var{fp})
	This sets the stream to which @sc{libassuan} should log messages not
	associated with a specific context to @var{fp}. The default is to log
	to @code{stderr}. This default value is also changed by using
	@code{assuan_set_log_stream} (to set a logging stream for a specific
	context) unless this function has been used. Obviously this is not
	thread-asfe and thus it is highly recommended to use this function to
	setup a proper default.
	@end deftypefun

	@deftypefun void assuan_set_assuan_log_prefix (@w{const char *@var{text}})
	Set the prefix to be used at the start of a line emitted by assuan
	on the log stream to @var{text}. The default is the empty string.
	@end deftypefun

	If you intend to use @sc{libassuan} along with the package
	@sc{libgpg-error} it is recommended to switch @sc{libassuan} into a mode
	which directly makes use of error codes provided by @sc{libgpg-error}.
	Because the Assuan error codes and those of gpg-error overlap, it is
	required to explictly request this. You do this by calling the function

	@deftypefun void assuan_set_assuan_err_source (int @var{errsource})
	Enable gpg-error style error codes. @var{errsource} is one of the
	gpg-error sources. Switching back to the old style mode is not
	possible. The usual way to call this function is
	@smallexample
	assuan_set_assuan_err_source (GPG_ERR_SOURCE_DEFAULT);
	@end smallexample
	@end deftypefun

	@node Reading and Writing
	@section How to communicate with the peer

	What would be a IPC library without the ability to read and write data?
	Not very useful. Libassuan has high level functions to take care of of
	the more boring stuff but eventully actually data needs to be written.

	@noindent
	The basic read and write functions are:

	@deftypefun assuan_error_t assuan_read_line (@w{assuan_context_t @var{ctx}}, @w{char *@var{line}}, @w{size_t @var{linelen}})

	Read the next line from the client or server and store a pointer to the
	buffer holding that line at the address @var{line}. The valid length of
	the lines is stored at the address of @var{linelen}. This buffer is
	valid until the next read operation on the same context @var{ctx}. You
	may modify the contet of this buffer. The buffer is invalid (i.e. must
	not be used) if an error is returned. This function returns @code{0} on
	success or an error code.
	@end deftypefun

	@deftypefun assuan_error_t assuan_write_line (@w{assuan_context_t @var{ctx}}, @w{const char *@var{line}})

	Write the string @var{line} to the other end. This string needs to be a
	proper formatted Assuan protocol line and should not include a linefeed.
	Sending linefeed or Nul characters is not possible and not alowed by the
	assuan protocol. This fucntion shall not be used for sendind data (D)
	lines. This function returns @code{0} on success or an error code.
	@end deftypefun

	@noindent
	To actually send bulk data lines a specialized function is available:

	@deftypefun assuan_error_t assuan_send_data (@w{assuan_context_t @var{ctx}}, @w{const void *@var{buffer}}, @w{size_t @var{length}})

	This function is used by a server or a client to send
	@var{length} bytes of bulk data in @var{buffer} to the other end.
	The data will be escaped as required by the Assuan protocol and
	may get buffered until a line is full. To force sending the data out
	@var{buffer} may be passed as @code{NULL} and @var{length} be @code{0}.

	When used by a client this flush operation does also send the
	terminating @code{END} command to terminate the response on an
	``INQUIRE'' response. Note, that the fucntion @code{assuan_transact}
	takes care of sending this @code{END} itself.

	@noindent
	This function returns @code{0} on success or an error code.
	@end deftypefun




	@c
	@c C L I E N T C O D E
	@c
	@node Client code
	@chapter How to develop an Assuan client




	assuan_error_t assuan_pipe_connect (assuan_context_t *ctx,
	const char *name,
	const char *const argv[],
	int *fd_child_list);
	assuan_error_t assuan_pipe_connect2 (assuan_context_t *ctx,
	const char *name,
	const char *const argv[],
	int *fd_child_list,
	void (atfork) (void, int),
	void *atforkvalue);
	assuan_error_t assuan_pipe_connect_ext (assuan_context_t *ctx,
	const char *name,
	const char *const argv[],
	int *fd_child_list,
	void (atfork) (void , int),
	void *atforkvalue,
	unsigned int flags);

	assuan_error_t assuan_socket_connect (assuan_context_t *ctx,
	const char *name,
	pid_t server_pid);
	assuan_error_t assuan_socket_connect_ext (assuan_context_t *ctx,
	const char *name,
	pid_t server_pid,
	unsigned int flags);

	void assuan_disconnect (assuan_context_t ctx);

	assuan_error_t
	assuan_transact (assuan_context_t ctx,
	const char *command,
	int (data_cb)(void , const void *, size_t),
	void *data_cb_arg,
	int (inquire_cb)(void, const char *),
	void *inquire_cb_arg,
	int (status_cb)(void, const char *),
	void *status_cb_arg);


	/* 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")). */
	assuan_error_t assuan_sendfd (assuan_context_t ctx, int fd);
	assuan_error_t assuan_receivefd (assuan_context_t ctx, int *fd);


	@c
	@c S E R V E R C O D E
	@c
	@node Server code
	@chapter How to develop an Assuan server

	bar
	int assuan_register_command (assuan_context_t ctx,
	const char *cmd_string,
	int (handler)(assuan_context_t, char ));
	int assuan_register_bye_notify (assuan_context_t ctx,
	void (*fnc)(assuan_context_t));
	int assuan_register_reset_notify (assuan_context_t ctx,
	void (*fnc)(assuan_context_t));
	int assuan_register_cancel_notify (assuan_context_t ctx,
	void (*fnc)(assuan_context_t));
	int assuan_register_input_notify (assuan_context_t ctx,
	void (fnc)(assuan_context_t, const char ));
	int assuan_register_output_notify (assuan_context_t ctx,
	void (fnc)(assuan_context_t, const char ));

	int assuan_register_option_handler (assuan_context_t ctx,
	int (*fnc)(assuan_context_t,
	const char, const char));

	int assuan_process (assuan_context_t ctx);
	int assuan_process_next (assuan_context_t ctx);

	FILE *assuan_get_data_fp (assuan_context_t ctx);
	assuan_error_t assuan_set_okay_line (assuan_context_t ctx, const char *line);
	assuan_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). */
	assuan_error_t assuan_command_parse_fd (assuan_context_t ctx, char *line,
	int *rfd);

	assuan_error_t assuan_set_hello_line (assuan_context_t ctx, const char *line);
	assuan_error_t assuan_accept (assuan_context_t ctx);
	int assuan_get_input_fd (assuan_context_t ctx);
	int assuan_get_output_fd (assuan_context_t ctx);
	assuan_error_t assuan_close_input_fd (assuan_context_t ctx);
	assuan_error_t assuan_close_output_fd (assuan_context_t ctx);

	int assuan_init_pipe_server (assuan_context_t *r_ctx, int filedes[2]);
	void assuan_deinit_server (assuan_context_t ctx);

	int assuan_init_socket_server (assuan_context_t *r_ctx, int listen_fd);
	int assuan_init_connected_socket_server (assuan_context_t *r_ctx, int fd);
	int assuan_init_socket_server_ext (assuan_context_t *r_ctx, int fd,
	unsigned int flags);

	assuan_error_t assuan_inquire (assuan_context_t ctx, const char *keyword,
	unsigned char *r_buffer, size_t r_length,
	size_t maxlen);



	@c
	@c U T I L I T I E S
	@c
	@node Utilities
	@chapter Utility functions


	void assuan_set_log_stream (assuan_context_t ctx, FILE *fp);
	int assuan_set_error (assuan_context_t ctx, int err, const char *text);
	void assuan_set_pointer (assuan_context_t ctx, void *pointer);
	void *assuan_get_pointer (assuan_context_t ctx);

	void assuan_begin_confidential (assuan_context_t ctx);
	void assuan_end_confidential (assuan_context_t ctx);

	/* 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);

	typedef enum
	/* When using a pipe server, by default Assuan will wait for the
	forked process to die in assuan_disconnect. 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. */
	ASSUAN_NO_WAITPID = 1
	assuan_flag_t;



	/* Return the VALUE of FLAG in context CTX. */
	int assuan_get_flag (assuan_context_t ctx, assuan_flag_t flag);


	const char *assuan_strerror (assuan_error_t err);


	@deftypefun pid_t assuan_get_pid (@w{assuan_context_t @var{ctx}})

	This function returns the pid of the connected connected peer. If that
	pid is not known @code{-1} is returned. Note that it is not always
	possible to learn the pid of the other process. For a pipe based server
	the client knows it instantly and a mechnism is in palce to let the
	server learn it. For socket based servers the pid is only available on
	systems providing the ``SO_PEERCRED'' socket option @footnote{to our
	knowledge only the Linux kernel has this feature}.
	@end deftypefun


	@deftypefun assuan_error_t assuan_get_peercred (@w{assuan_context_t @var{ctx}}, @w{pid_t @var{pid}}, @w{uid_t @var{uid}}, @w{gid_t *@var{pid}})

	Return user credentials of the peer. This will work only on certain
	systems and only when connected over a socket. If you are not
	interested in some of the values, pass @code{NULL} instead of the
	address of an appropriate variable. @var{pid}, @var{uid} and @var{gid}
	are only set if the function succeeds and returns with @code{0}.

	As of now only the server is able to retrieve this information. Note,
	that for getting the pid of the peer @code{assuan_get_pid} is usually
	better suited.
	@end deftypefun


	int assuan_get_active_fds (assuan_context_t ctx, int what,
	int *fdarray, int fdarraysize);

	int assuan_pending_line (assuan_context_t ctx);

	/* Return the stream which is currently being using for global logging. */
	FILE *assuan_get_assuan_log_stream (void);

	/* 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);


	@c ---------------------------------------------------------------------
	@c Legal BS
	@c ---------------------------------------------------------------------

	@include lgpl.texi
	@include gpl.texi


	@c ---------------------------------------------------------------------
	@c Indexes
	@c ---------------------------------------------------------------------

	@node Index
	@unnumbered Index

	@printindex cp

	@c ---------------------------------------------------------------------
	@c Epilogue
	@c ---------------------------------------------------------------------

	@bye

File Metadata

Mime Type: text/x-tex
Expires: Sat, May 10, 9:15 AM (7 h, 41 m)
Storage Engine: local-disk
Storage Format: Raw Data
Storage Handle: db/6c/0aa3d942b45d52973b031994fe47

assuan.texiNo OneTemporaryActions

assuan.texiView Options

File Metadata

Event Timeline

assuan.texi
No OneTemporary
Actions

assuan.texi
View Options