|
Packit |
3c2767 |
\input texinfo @c -*-texinfo-*-
|
|
Packit |
3c2767 |
@c %**start of header
|
|
Packit |
3c2767 |
@setfilename assuan.info
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@macro copyrightnotice
|
|
Packit |
3c2767 |
Copyright @copyright{} 2001--2013 Free Software Foundation, Inc. @*
|
|
Packit |
3c2767 |
Copyright @copyright{} 2001--2015 g10 Code GmbH
|
|
Packit |
3c2767 |
@end macro
|
|
Packit |
3c2767 |
@macro permissionnotice
|
|
Packit |
3c2767 |
Permission is granted to copy, distribute and/or modify this document
|
|
Packit |
3c2767 |
under the terms of the GNU General Public License as published by the
|
|
Packit |
3c2767 |
Free Software Foundation; either version 3 of the License, or (at your
|
|
Packit |
3c2767 |
option) any later version. The text of the license can be found in the
|
|
Packit |
3c2767 |
section entitled ``Copying''.
|
|
Packit |
3c2767 |
@end macro
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@include version.texi
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@settitle Developing with Assuan
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c Create a separate index for command line options.
|
|
Packit |
3c2767 |
@defcodeindex op
|
|
Packit |
3c2767 |
@c Merge the standard indexes into a single one.
|
|
Packit |
3c2767 |
@syncodeindex fn cp
|
|
Packit |
3c2767 |
@syncodeindex vr cp
|
|
Packit |
3c2767 |
@syncodeindex ky cp
|
|
Packit |
3c2767 |
@syncodeindex pg cp
|
|
Packit |
3c2767 |
@syncodeindex tp cp
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c A simple macro for optional variables.
|
|
Packit |
3c2767 |
@macro ovar{varname}
|
|
Packit |
3c2767 |
@r{[}@var{\varname\}@r{]}
|
|
Packit |
3c2767 |
@end macro
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c printing stuff taken from gcc.
|
|
Packit |
3c2767 |
@macro gnupgtabopt{body}
|
|
Packit |
3c2767 |
@code{\body\}
|
|
Packit |
3c2767 |
@end macro
|
|
Packit |
3c2767 |
@macro gnupgoptlist{body}
|
|
Packit |
3c2767 |
@smallexample
|
|
Packit |
3c2767 |
\body\
|
|
Packit |
3c2767 |
@end smallexample
|
|
Packit |
3c2767 |
@end macro
|
|
Packit |
3c2767 |
@c Makeinfo handles the above macro OK, TeX needs manual line breaks;
|
|
Packit |
3c2767 |
@c they get lost at some point in handling the macro. But if @macro is
|
|
Packit |
3c2767 |
@c used here rather than @alias, it produces double line breaks.
|
|
Packit |
3c2767 |
@iftex
|
|
Packit |
3c2767 |
@alias gol = *
|
|
Packit |
3c2767 |
@end iftex
|
|
Packit |
3c2767 |
@ifnottex
|
|
Packit |
3c2767 |
@macro gol
|
|
Packit |
3c2767 |
@end macro
|
|
Packit |
3c2767 |
@end ifnottex
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c Change the font used for @def... commands, since the default
|
|
Packit |
3c2767 |
@c proportional one used is bad for names starting __.
|
|
Packit |
3c2767 |
@tex
|
|
Packit |
3c2767 |
\gdef\mysetfont#1#2#3#4{\font#1=\fontprefix#2#3 scaled #4}
|
|
Packit |
3c2767 |
\global\mysetfont\defbf\ttbshape{10}{\magstep1}
|
|
Packit |
3c2767 |
@end tex
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c %**end of header
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@ifnottex
|
|
Packit |
3c2767 |
@dircategory GNU Libraries
|
|
Packit |
3c2767 |
@direntry
|
|
Packit |
3c2767 |
* Assuan: (assuan). An IPC library for non-persistent servers.
|
|
Packit |
3c2767 |
@end direntry
|
|
Packit |
3c2767 |
This file documents the use and the internals of Assuan.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This is Edition @value{EDITION}, last updated @value{UPDATED}, of
|
|
Packit |
3c2767 |
@cite{The `Developing with Assuan' Manual}, for Version @value{VERSION}.
|
|
Packit |
3c2767 |
@sp 1
|
|
Packit |
3c2767 |
Published by the Free Software Foundation@*
|
|
Packit |
3c2767 |
51 Franklin Street, Fifth Floor@*
|
|
Packit |
3c2767 |
Boston, MA 02110-1301 USA
|
|
Packit |
3c2767 |
@sp 1
|
|
Packit |
3c2767 |
@copyrightnotice{}
|
|
Packit |
3c2767 |
@sp 1
|
|
Packit |
3c2767 |
@permissionnotice{}
|
|
Packit |
3c2767 |
@end ifnottex
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@setchapternewpage odd
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@titlepage
|
|
Packit |
3c2767 |
@title Developing with Assuan
|
|
Packit |
3c2767 |
@subtitle Version @value{VERSION}
|
|
Packit |
3c2767 |
@subtitle @value{UPDATED}
|
|
Packit |
3c2767 |
@author by Werner Koch and Marcus Brinkmann
|
|
Packit |
3c2767 |
@author @code{@{wk,mb@}@@g10code.com}
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@page
|
|
Packit |
3c2767 |
@vskip 0pt plus 1filll
|
|
Packit |
3c2767 |
@copyrightnotice{}
|
|
Packit |
3c2767 |
@sp 2
|
|
Packit |
3c2767 |
@permissionnotice{}
|
|
Packit |
3c2767 |
@end titlepage
|
|
Packit |
3c2767 |
@summarycontents
|
|
Packit |
3c2767 |
@contents
|
|
Packit |
3c2767 |
@page
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@ifnottex
|
|
Packit |
3c2767 |
@node Top
|
|
Packit |
3c2767 |
@top Introduction
|
|
Packit |
3c2767 |
@cindex introduction
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This manual documents how to exploit the Assuan library, a simple
|
|
Packit |
3c2767 |
interprocess communcation library.
|
|
Packit |
3c2767 |
@end ifnottex
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@menu
|
|
Packit |
3c2767 |
* Introduction:: An introduction to and the motivation behind Assuan.
|
|
Packit |
3c2767 |
* Assuan:: Description of the Assuan protocol.
|
|
Packit |
3c2767 |
* Implementation:: Overview of the implementation.
|
|
Packit |
3c2767 |
* Preparation:: What you should do before using the library.
|
|
Packit |
3c2767 |
* Generalities:: Initialization code and data types used.
|
|
Packit |
3c2767 |
* Client code:: How to develop an Assuan client.
|
|
Packit |
3c2767 |
* Server code:: How to develop an Assuan server.
|
|
Packit |
3c2767 |
* External I/O Loop:: How to use external I/O event loops.
|
|
Packit |
3c2767 |
* Utilities:: Utility functions.
|
|
Packit |
3c2767 |
* Socket wrappers:: Socket wrapper functions.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Miscellaneous
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
* Library Copying:: GNU Lesser General Public License says
|
|
Packit |
3c2767 |
how you can copy and share Assuan.
|
|
Packit |
3c2767 |
* Copying:: How you can copy and share this manual.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Indices
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
* Index:: Index of concepts and symbol names.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@end menu
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@c I N T R O
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@node Introduction
|
|
Packit |
3c2767 |
@chapter Introduction to Assuan
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Assuan is an extensible inter-process communication (IPC) protocol and
|
|
Packit |
3c2767 |
library. It is designed for point-to-point communication and it
|
|
Packit |
3c2767 |
doesn't provide a naming system. To contact a server, either the
|
|
Packit |
3c2767 |
client must know how to locate the server, e.g., via a well-known Unix
|
|
Packit |
3c2767 |
domain socket, or, if the server is transient, how to start it. In
|
|
Packit |
3c2767 |
the latter case, Assuan provides functionality to start the server
|
|
Packit |
3c2767 |
process.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
In Assuan, communication is typically either via a pipe or a Unix
|
|
Packit |
3c2767 |
domain socket. This method is neither elegant nor efficient,
|
|
Packit |
3c2767 |
especially when there is a lot of data spread across several
|
|
Packit |
3c2767 |
transactions. Not only is there a penalty for an increased number of
|
|
Packit |
3c2767 |
context switches, but a significant amount of data is @var{memcpy}ed
|
|
Packit |
3c2767 |
from the client to a file descriptor and from the file descriptor to
|
|
Packit |
3c2767 |
the server. Despite these and other disadvantages, this type of
|
|
Packit |
3c2767 |
client/server communication is useful: the client is separated from
|
|
Packit |
3c2767 |
the server: they run in different address spaces. This is especially
|
|
Packit |
3c2767 |
important in situations where the server must have a known degree of
|
|
Packit |
3c2767 |
reliability and data must be protected: as the Assuan protocol is well
|
|
Packit |
3c2767 |
defined and clients cannot corrupt the servers' address space,
|
|
Packit |
3c2767 |
auditing becomes much easier.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Assuan was developed for use by the GNU Privacy Guard (GnuPG) to
|
|
Packit |
3c2767 |
prevent potentially buggy clients from unwittingly corrupting
|
|
Packit |
3c2767 |
sensitive transactions or compromising data such as a secret key.
|
|
Packit |
3c2767 |
Assuan permits the servers, which do the actual work, e.g., encryption
|
|
Packit |
3c2767 |
and decryption of data using a secret key, to be developed
|
|
Packit |
3c2767 |
independently of the user interfaces, e.g., mail clients and other
|
|
Packit |
3c2767 |
encryption front ends. Like a shared library, the interface is well
|
|
Packit |
3c2767 |
defined and any number of front ends can use it; however, unlike a
|
|
Packit |
3c2767 |
shared library, the client cannot see or touch the server's data. As
|
|
Packit |
3c2767 |
with any modular system, Assuan helps keep the components small,
|
|
Packit |
3c2767 |
understandable and less error prone.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Assuan is not, however, limited to use with GnuPG servers and clients:
|
|
Packit |
3c2767 |
it was designed to be flexible enough to meet the demands of many
|
|
Packit |
3c2767 |
transaction-based environments.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Assuan
|
|
Packit |
3c2767 |
@chapter Description of the Assuan protocol.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The architecture of the modular GnuPG system is based on several
|
|
Packit |
3c2767 |
highly specialized modules which form a network of clients and
|
|
Packit |
3c2767 |
servers. A common framework for intermodule communication is
|
|
Packit |
3c2767 |
therefore needed and implemented as a library.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Goals:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@itemize @bullet
|
|
Packit |
3c2767 |
@item Common framework for module communication
|
|
Packit |
3c2767 |
@item Easy debugging
|
|
Packit |
3c2767 |
@item Easy module testing
|
|
Packit |
3c2767 |
@item Extensible
|
|
Packit |
3c2767 |
@item Optional authentication and encryption facility
|
|
Packit |
3c2767 |
@item Usable to access external hardware
|
|
Packit |
3c2767 |
@end itemize
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Design criteria:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@itemize @bullet
|
|
Packit |
3c2767 |
@item Client/Server with back channel
|
|
Packit |
3c2767 |
@item Use a mainly text based protocol
|
|
Packit |
3c2767 |
@item Escape certain control characters
|
|
Packit |
3c2767 |
@item Allow indefinite data length
|
|
Packit |
3c2767 |
@item Request confidentiality for parts of the communication
|
|
Packit |
3c2767 |
@item Dummy module to allow direct linking of client and server
|
|
Packit |
3c2767 |
@item Inline data or descriptor passing for bulk data
|
|
Packit |
3c2767 |
@item No protection against DoS needed
|
|
Packit |
3c2767 |
@item Subliminal channels are not an issue
|
|
Packit |
3c2767 |
@end itemize
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Implementation
|
|
Packit |
3c2767 |
@chapter Implementation
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The implementation is line based with a maximum line size of 1000
|
|
Packit |
3c2767 |
octets. The default IPC mechanism is Unix Domain Sockets.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
On connect, the server responds either with okay or an error status.
|
|
Packit |
3c2767 |
To perform an authentication check, the server may send an Inquiry
|
|
Packit |
3c2767 |
response prior to the first Okay. It may also issue Status messages.
|
|
Packit |
3c2767 |
The server must check that the client is allowed to connect. This is
|
|
Packit |
3c2767 |
done by requesting the credentials for the peer and comparing them
|
|
Packit |
3c2767 |
with the server's credentials. This avoids attacks based on wrong
|
|
Packit |
3c2767 |
socket permissions.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The server may choose to delay the first response in case of an error.
|
|
Packit |
3c2767 |
The server, however, never closes the connection, however, the lower
|
|
Packit |
3c2767 |
protocol may do so after some time of inactivity or when the
|
|
Packit |
3c2767 |
connection enters an error state.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
All textual messages are assumed to be in UTF-8 unless otherwise noted.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@menu
|
|
Packit |
3c2767 |
* Server responses:: Description of server responses.
|
|
Packit |
3c2767 |
* Client requests:: Description of client requests.
|
|
Packit |
3c2767 |
* Error codes:: List of error and status codes.
|
|
Packit |
3c2767 |
@end menu
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Server responses
|
|
Packit |
3c2767 |
@section Server responses
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item OK [<arbitrary debugging information>]
|
|
Packit |
3c2767 |
Request was successful.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item ERR @var{errorcode} [<human readable error description>]
|
|
Packit |
3c2767 |
Request could not be fulfilled. The possible error codes are defined
|
|
Packit |
3c2767 |
by @code{libgpg-error}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item S @var{keyword} <status information depending on keyword>
|
|
Packit |
3c2767 |
Informational output by the server, which is still processing the
|
|
Packit |
3c2767 |
request. A client may not send such lines to the server while
|
|
Packit |
3c2767 |
processing an Inquiry command. @var{keyword} shall start with a
|
|
Packit |
3c2767 |
letter or an underscore.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item # <string>
|
|
Packit |
3c2767 |
Comment line issued only for debugging purposes. Totally ignored.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item D <raw data>
|
|
Packit |
3c2767 |
Raw data returned to client. There must be exactly one space after the
|
|
Packit |
3c2767 |
'D'. The values for '%', CR and LF must be percent escaped; these are
|
|
Packit |
3c2767 |
encoded as %25, %0D and %0A, respectively. Only uppercase letters
|
|
Packit |
3c2767 |
should be used in the hexadecimal representation. Other characters
|
|
Packit |
3c2767 |
may be percent escaped for easier debugging. All Data lines are
|
|
Packit |
3c2767 |
considered one data stream up to the OK or ERR response. Status and
|
|
Packit |
3c2767 |
Inquiry Responses may be mixed with the Data lines.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item INQUIRE @var{keyword} <parameters>
|
|
Packit |
3c2767 |
The server needs further information from the client. The client
|
|
Packit |
3c2767 |
should respond with data (using the ``D'' command and terminated by
|
|
Packit |
3c2767 |
``END''). Alternatively, the client may cancel the current operation
|
|
Packit |
3c2767 |
by responding with ``CAN''.
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Consider the following examples (lines prefixed with S indicate text
|
|
Packit |
3c2767 |
that the server sends; lines prefixed with C indicate text that the
|
|
Packit |
3c2767 |
client sends):
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
S: INQUIRE foo
|
|
Packit |
3c2767 |
C: D foo bar
|
|
Packit |
3c2767 |
C: D bar baz
|
|
Packit |
3c2767 |
C: END
|
|
Packit |
3c2767 |
[Server continues normal work]
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This implements a callback to the client:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
S: INQUIRE foo
|
|
Packit |
3c2767 |
C: END
|
|
Packit |
3c2767 |
[Server continues]
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
and:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
S: INQUIRE foo
|
|
Packit |
3c2767 |
C: CAN
|
|
Packit |
3c2767 |
[Server terminates the operaion and in most cases returns an ERR to the client.]
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
But, CAN may also mean ``I have no data for you, try to get it from
|
|
Packit |
3c2767 |
elsewhere.''
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Note: lines longer than 1000 bytes should be treated as a
|
|
Packit |
3c2767 |
communication error. (The rationale for having a line length limit is
|
|
Packit |
3c2767 |
to allow for easier multiplexing of several channels.)
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Client requests
|
|
Packit |
3c2767 |
@section Client requests
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The server waits for client requests after sending an Okay or Error.
|
|
Packit |
3c2767 |
The client should not issue a request in other cases.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
@var{command} <parameters>
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@var{command} is a one word string without preceding white space.
|
|
Packit |
3c2767 |
Parameters are command specific, CR, LF and the percent signs should
|
|
Packit |
3c2767 |
be percent escaped as described above. To send a backslash as the
|
|
Packit |
3c2767 |
last character it should also be percent escaped. Percent escaping is
|
|
Packit |
3c2767 |
allowed anywhere in the parameters but not in the command. The line
|
|
Packit |
3c2767 |
ends with a CR, LF pair or just a LF.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Not yet implemented feature: If there is a need for a parameter list
|
|
Packit |
3c2767 |
longer than the line length limit (1000 characters including command
|
|
Packit |
3c2767 |
and CR, LF), the last character of the line (right before the CR/LF or
|
|
Packit |
3c2767 |
LF) must be a unescaped (i.e., literal) backslash. The following line
|
|
Packit |
3c2767 |
is then expected to be a continuation of the line with the backslash
|
|
Packit |
3c2767 |
replaced by a blank and the line ending removed.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
D <raw data>
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Sends raw data to the server. There must be exactly one space after
|
|
Packit |
3c2767 |
the 'D'. The values for '%', CR and LF must be percent escaped.
|
|
Packit |
3c2767 |
These are encoded as %25, %0D and %0A, respectively. Only uppercase
|
|
Packit |
3c2767 |
letters should be used in the hexadecimal representation. Other
|
|
Packit |
3c2767 |
characters may be percent escaped for easier debugging. All Data
|
|
Packit |
3c2767 |
lines are considered one data stream up to the @code{OK} or @code{ERR}
|
|
Packit |
3c2767 |
response. Status and Inquiry Responses may be mixed with the Data
|
|
Packit |
3c2767 |
lines.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
END
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Lines beginning with a @code{#} or empty lines are ignored. This is
|
|
Packit |
3c2767 |
useful to comment test scripts.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Although the commands are application specific, some of them are used
|
|
Packit |
3c2767 |
by all protocols and partly supported by the Assuan library:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item BYE
|
|
Packit |
3c2767 |
Close the connection. The server will respond with @code{OK}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item RESET
|
|
Packit |
3c2767 |
Reset the connection but not any existing authentication. The server
|
|
Packit |
3c2767 |
should release all resources associated with the connection.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item END
|
|
Packit |
3c2767 |
Used by a client to mark the end of raw data. The server may send
|
|
Packit |
3c2767 |
@code{END} to indicate a partial end of data.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item HELP
|
|
Packit |
3c2767 |
Lists all commands that the server understands as comment lines on the
|
|
Packit |
3c2767 |
status channel.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item QUIT
|
|
Packit |
3c2767 |
Reserved for future extensions.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item OPTION
|
|
Packit |
3c2767 |
Set options for the connection. The syntax of such a line is
|
|
Packit |
3c2767 |
@display
|
|
Packit |
3c2767 |
OPTION @var{name} [ [=] @var{value} ]
|
|
Packit |
3c2767 |
@end display
|
|
Packit |
3c2767 |
Leading and trailing spaces around @var{name} and @var{value} are
|
|
Packit |
3c2767 |
allowed but should be ignored. For compatibility reasons, @var{name}
|
|
Packit |
3c2767 |
may be prefixed with two dashes. The use of the equal sign is optional
|
|
Packit |
3c2767 |
but suggested if @var{value} is given.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item CANCEL
|
|
Packit |
3c2767 |
This command is reserved for future extensions.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item AUTH
|
|
Packit |
3c2767 |
This command is reserved for future extensions. Not yet specified as
|
|
Packit |
3c2767 |
we don't implement it in the first phase. See Werner's mail to gpa-dev on
|
|
Packit |
3c2767 |
2001-10-25 about the rationale for measurements against local attacks.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item NOP
|
|
Packit |
3c2767 |
No operation. Returns OK without any action.
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Error codes
|
|
Packit |
3c2767 |
@section Error codes
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Libassuan is used with gpg-error style error codes. It is recommended
|
|
Packit |
3c2767 |
to set the error source to a different value from the default
|
|
Packit |
3c2767 |
@code{GPG_ERR_SOURCE_UNKNOWN} by calling @ref{function
|
|
Packit |
3c2767 |
assuan_set_gpg_err_source} early.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@c P R E P A R A T I O N
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@node Preparation
|
|
Packit |
3c2767 |
@chapter Preparation
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
To use @sc{Assuan}, you have to make some changes to your
|
|
Packit |
3c2767 |
sources and the build system. The necessary changes are small and
|
|
Packit |
3c2767 |
explained in the following sections.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@menu
|
|
Packit |
3c2767 |
* Header:: What header file you need to include.
|
|
Packit |
3c2767 |
* Building sources:: How to build sources using the library.
|
|
Packit |
3c2767 |
* Automake:: How to build sources with the help of Automake.
|
|
Packit |
3c2767 |
* Multi Threading:: How @code{libassuan} can be used in a MT environment.
|
|
Packit |
3c2767 |
@end menu
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Header
|
|
Packit |
3c2767 |
@section Header
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
All interfaces (data types and functions) of @code{libassuan} are defined
|
|
Packit |
3c2767 |
in the header file @file{assuan.h}. You must include this in all source
|
|
Packit |
3c2767 |
files using the library, either directly or through some other header
|
|
Packit |
3c2767 |
file, like this:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
#include <assuan.h>
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The namespace of @code{libassuan} is @code{assuan_*} for function
|
|
Packit |
3c2767 |
and type names and @code{ASSUAN*} for other symbols. In addition the
|
|
Packit |
3c2767 |
same name prefixes with one prepended underscore are reserved for
|
|
Packit |
3c2767 |
internal use and should never be used by an application.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Because @code{libassuan} makes use of the GPG Error library, using
|
|
Packit |
3c2767 |
@code{libassuan} will also use the @code{GPG_ERR_*} namespace
|
|
Packit |
3c2767 |
directly, and the @code{gpg_err*} and @code{gpg_str*} namespaces
|
|
Packit |
3c2767 |
indirectly.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Building sources
|
|
Packit |
3c2767 |
@section Building sources
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
If you want to compile a source file including the @file{assuan.h}
|
|
Packit |
3c2767 |
header file, you must make sure that the compiler can find it in the
|
|
Packit |
3c2767 |
directory hierarchy. This is accomplished by adding the path to the
|
|
Packit |
3c2767 |
directory in which the header file is located to the compilers include
|
|
Packit |
3c2767 |
file search path (via the @option{-I} option).
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
However, the path to the include file is determined at the time the
|
|
Packit |
3c2767 |
source is configured. To solve this problem, @code{libassuan} ships with
|
|
Packit |
3c2767 |
a small helper program @command{libassuan-config} that knows the path to
|
|
Packit |
3c2767 |
the include file and other configuration options. The options that need
|
|
Packit |
3c2767 |
to be added to the compiler invocation at compile time are output by the
|
|
Packit |
3c2767 |
@option{--cflags} option to @command{libassuan-config}. The following
|
|
Packit |
3c2767 |
example shows how it can be used at the command line:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
gcc -c foo.c $(libassuan-config --cflags)
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Adding the output of @samp{libassuan-config --cflags} to the compiler's
|
|
Packit |
3c2767 |
command line will ensure that the compiler can find the @file{assuan.h}
|
|
Packit |
3c2767 |
header file.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
A similar problem occurs when linking the program with the library.
|
|
Packit |
3c2767 |
Again, the compiler/linker has to find the library files. For this to
|
|
Packit |
3c2767 |
work, the path to the library files has to be added to the library
|
|
Packit |
3c2767 |
search path (via the @option{-L} option). For this, the option
|
|
Packit |
3c2767 |
@option{--libs} to @command{libassuan-config} can be used. For
|
|
Packit |
3c2767 |
convenience, this option also outputs all other options that are
|
|
Packit |
3c2767 |
required to link the program with the @code{libassuan} libraries (in
|
|
Packit |
3c2767 |
particular, the @option{-lassuan} option). The example shows how to
|
|
Packit |
3c2767 |
link @file{foo.o} with the @code{libassuan} library to a program
|
|
Packit |
3c2767 |
@command{foo}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
gcc -o foo foo.o $(libassuan-config --libs)
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
You can also combine both examples to a single command by specifying
|
|
Packit |
3c2767 |
both options to @command{libassuan-config}:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
gcc -o foo foo.c $(libassuan-config --cflags --libs)
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Automake
|
|
Packit |
3c2767 |
@section Building sources using Automake
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
It is much easier if you use GNU Automake instead of writing your own
|
|
Packit |
3c2767 |
Makefiles. If you do that you do not have to worry about finding and
|
|
Packit |
3c2767 |
invoking the @command{libassuan-config} script at all. @code{libassuan}
|
|
Packit |
3c2767 |
provides an Automake macro that does all the work for you.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@defmac AM_PATH_LIBASSUAN (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
|
|
Packit |
3c2767 |
Check whether @code{libassuan} (at least version
|
|
Packit |
3c2767 |
@var{minimum-version}, if given) exists on the host system. If it is
|
|
Packit |
3c2767 |
found, execute @var{action-if-found}, otherwise do
|
|
Packit |
3c2767 |
@var{action-if-not-found}, if given.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Additionally, the function defines @code{LIBASSUAN_CFLAGS} to the
|
|
Packit |
3c2767 |
flags needed for compilation of the program to find the
|
|
Packit |
3c2767 |
@file{assuan.h} header file, and @code{LIBASSUAN_LIBS} to the linker
|
|
Packit |
3c2767 |
flags needed to link the program to the @code{libassuan} library.
|
|
Packit |
3c2767 |
@end defmac
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
You can use the defined Autoconf variables like this in your
|
|
Packit |
3c2767 |
@file{Makefile.am}:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
AM_CPPFLAGS = $(LIBASSUAN_CFLAGS)
|
|
Packit |
3c2767 |
LDADD = $(LIBASSUAN_LIBS)
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Multi Threading
|
|
Packit |
3c2767 |
@section Multi Threading
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The @code{libassuan} library is designed so that it can be used in a
|
|
Packit |
3c2767 |
threaded application, if some rules are followed.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@itemize @bullet
|
|
Packit |
3c2767 |
@item Run the initialization functions before you actually start
|
|
Packit |
3c2767 |
to use threads. Specifically, the functions
|
|
Packit |
3c2767 |
@code{assuan_set_gpg_err_source}, @code{assuan_set_malloc_hooks} and
|
|
Packit |
3c2767 |
@code{assuan_set_log_cb} should not be called concurrently with
|
|
Packit |
3c2767 |
@code{assuan_new}. Use @code{assuan_new_ext} instead or ensure proper
|
|
Packit |
3c2767 |
serialization.
|
|
Packit |
3c2767 |
@item Only one thread at a time may access an @code{libassuan} context.
|
|
Packit |
3c2767 |
@item If you use the default log handler, use
|
|
Packit |
3c2767 |
@code{assuan_set_assuan_log_stream} to setup a default log stream.
|
|
Packit |
3c2767 |
@item If you have callback functions shared by multiple functions,
|
|
Packit |
3c2767 |
the callback function must be reentrant for that purpose.
|
|
Packit |
3c2767 |
@code{libassuan} does not serialize invocation of callback functions
|
|
Packit |
3c2767 |
across contexts.
|
|
Packit |
3c2767 |
@end itemize
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@c G E N E R A L I T I E S
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@node Generalities
|
|
Packit |
3c2767 |
@chapter Generalities
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@menu
|
|
Packit |
3c2767 |
* Data Types:: Data types used by @code{libassuan}.
|
|
Packit |
3c2767 |
* Initializing the library:: How to initialize the library.
|
|
Packit |
3c2767 |
* Default Log Handler:: How to configure the default log handler.
|
|
Packit |
3c2767 |
* Contexts:: How to work with contexts.
|
|
Packit |
3c2767 |
* Reading and Writing:: How to communicate with the peer.
|
|
Packit |
3c2767 |
@end menu
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Data Types
|
|
Packit |
3c2767 |
@section Data Types used by the library
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@sc{Assuan} uses a so-called context to store a connection's state.
|
|
Packit |
3c2767 |
The following data type is used for that:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftp {Data type} assuan_context_t
|
|
Packit |
3c2767 |
The @code{assuan_context_t} type is a pointer to an object maintained
|
|
Packit |
3c2767 |
internally by the library. Contexts are allocated with
|
|
Packit |
3c2767 |
@code{assuan_new} or @code{assuan_new_ext} and released with
|
|
Packit |
3c2767 |
@code{assuan_release}. Other functions take this data type to access
|
|
Packit |
3c2767 |
the state created by these functions.
|
|
Packit |
3c2767 |
@end deftp
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftp {Data type} assuan_fd_t
|
|
Packit |
3c2767 |
The @code{assuan_fd_t} is a file descriptor (in Unix) or a system
|
|
Packit |
3c2767 |
handle (in Windows). The special value @code{ASSUAN_INVALID_FD} is
|
|
Packit |
3c2767 |
used to specify invalid Assuan file descriptors.
|
|
Packit |
3c2767 |
@end deftp
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun assuan_fd_t assuan_fdopen (@w{int @var{fd}})
|
|
Packit |
3c2767 |
Create an assuan file descriptor from a POSIX (libc) file descriptor
|
|
Packit |
3c2767 |
@var{fd}. On Unix, this is equivalent to @code{dup}, while on Windows
|
|
Packit |
3c2767 |
this will retrieve the underlying system handle with
|
|
Packit |
3c2767 |
@code{_get_osfhandle} and duplicate that.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Initializing the library
|
|
Packit |
3c2767 |
@section Initializing the library
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Libassuan makes use of Libgpg-error and assumes that Libgpg-error has
|
|
Packit |
3c2767 |
been initialized. In general @code{gpgrt_check_version} should be
|
|
Packit |
3c2767 |
called to guarantee this; the Libgpg-error manual for details.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Libassuan itself requires no initialization. There are however some
|
|
Packit |
3c2767 |
initialization hooks provided which are often useful. These should be
|
|
Packit |
3c2767 |
called as early as possible and in a multi-threaded application before
|
|
Packit |
3c2767 |
a second thread is created.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
These functions initialize default values that are used at context
|
|
Packit |
3c2767 |
creation with @code{assuan_new}. As there can only be one default,
|
|
Packit |
3c2767 |
all values can also be set directly with @code{assuan_new_ext} or with
|
|
Packit |
3c2767 |
context-specific functions after context creation.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
If your application uses its own memory allocation functions or wrappers
|
|
Packit |
3c2767 |
it is good idea to tell @code{libassuan} about it so it can make use of the
|
|
Packit |
3c2767 |
same functions or wrappers:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftp {Data type} {struct assuan_malloc_hooks}
|
|
Packit |
3c2767 |
This structure is used to store the memory allocation callback
|
|
Packit |
3c2767 |
interface functions. It has the following members, whose semantics
|
|
Packit |
3c2767 |
are identical to the corresponding system functions:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item void *(*malloc) (size_t cnt)
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to allocate memory for a context.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item void *(*realloc) (void *ptr, size_t cnt)
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to reallocate memory for a context.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item void (*free) (void *ptr)
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to release memory for a context.
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
@end deftp
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftp {Data type} {assuan_malloc_hooks_t}
|
|
Packit |
3c2767 |
This is a pointer to a @code{struct assuan_malloc_hooks}.
|
|
Packit |
3c2767 |
@end deftp
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_set_malloc_hooks (@w{assuan_malloc_hooks_t @var{malloc_hooks}})
|
|
Packit |
3c2767 |
This function sets the default allocation hooks for new contexts
|
|
Packit |
3c2767 |
allocated with @code{assuan_new}. You need to provide all three
|
|
Packit |
3c2767 |
functions. Those functions need to behave exactly as their standard
|
|
Packit |
3c2767 |
counterparts @code{malloc}, @code{realloc} and @code{free}. If you
|
|
Packit |
3c2767 |
write your own functions, please take care to set @code{errno}
|
|
Packit |
3c2767 |
whenever an error has occurred.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun assuan_malloc_hooks_t assuan_get_malloc_hooks ()
|
|
Packit |
3c2767 |
This function gets the default allocation hooks for new contexts
|
|
Packit |
3c2767 |
allocated with @code{assuan_new}. The result structure is statically
|
|
Packit |
3c2767 |
allocated and should not be modified.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The @sc{Assuan} library uses @code{libgpg-error} error values, which
|
|
Packit |
3c2767 |
consist and error code and an error source. The default source used
|
|
Packit |
3c2767 |
by contexts allocated with @code{assuan_new} can be set with the
|
|
Packit |
3c2767 |
following function.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@anchor{function assuan_set_gpg_err_source}
|
|
Packit |
3c2767 |
@deftypefun void assuan_set_gpg_err_source (@w{gpg_err_source_t @var{err_source}})
|
|
Packit |
3c2767 |
This function sets the default error source for errors generated by
|
|
Packit |
3c2767 |
contexts allocated with @code{assuan_new}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
One way to call this function is
|
|
Packit |
3c2767 |
@smallexample
|
|
Packit |
3c2767 |
assuan_set_gpg_err_source (GPG_ERR_SOURCE_DEFAULT);
|
|
Packit |
3c2767 |
@end smallexample
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_err_source_t assuan_get_gpg_err_source (void)
|
|
Packit |
3c2767 |
This function gets the default error source for errors generated by
|
|
Packit |
3c2767 |
contexts allocated with @code{assuan_new}.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
To integrate assuan logging and diagnostics into your own logging
|
|
Packit |
3c2767 |
system, you may use the following two functions:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftp {Data type} {int (*assuan_log_cb_t) (@w{assuan_context_t @var{ctx}}, @w{void *@var{hook_value}}, @w{unsigned int @var{cat}}, @w{const char *@var{msg}})}
|
|
Packit |
3c2767 |
The user-provided callback function takes a context @var{ctx}, for
|
|
Packit |
3c2767 |
which the message @var{msg} was generated, and a hook value
|
|
Packit |
3c2767 |
@var{hook_value} that was supplied when the log handler was registered
|
|
Packit |
3c2767 |
for the context with @code{assuan_set_log_cb}, and a category
|
|
Packit |
3c2767 |
@var{cat}. The category is one of:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item ASSUAN_LOG_INIT
|
|
Packit |
3c2767 |
@item ASSUAN_LOG_CTX
|
|
Packit |
3c2767 |
@item ASSUAN_LOG_ENGINE
|
|
Packit |
3c2767 |
@item ASSUAN_LOG_DATA
|
|
Packit |
3c2767 |
RFU
|
|
Packit |
3c2767 |
@item ASSUAN_LOG_SYSIO
|
|
Packit |
3c2767 |
Log lowlevel I/O data.
|
|
Packit |
3c2767 |
@item ASSUAN_LOG_CONTROL
|
|
Packit |
3c2767 |
Log the control channel.
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The user may then, depending on the category, write the message to a
|
|
Packit |
3c2767 |
log file or treat it in some other way.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
If @var{msg} is a null pointer, then no message should be logged, but
|
|
Packit |
3c2767 |
the function should return 1 if it is interested in log messages with
|
|
Packit |
3c2767 |
the category @var{cat}. If it is not interested, 0 should be
|
|
Packit |
3c2767 |
returned. This allows @code{libassuan} to suppress the generation of
|
|
Packit |
3c2767 |
expensive debug output.
|
|
Packit |
3c2767 |
@end deftp
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_set_log_cb (@w{assuan_log_cb_t @var{log_cb}}, @w{void *@var{log_cb_data}})
|
|
Packit |
3c2767 |
This function sets the default logging handler for log messages
|
|
Packit |
3c2767 |
generated by contexts allocated with @code{assuan_new}.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_get_log_cb (@w{assuan_log_cb_t *@var{log_cb}}, @w{void **@var{log_cb_data}})
|
|
Packit |
3c2767 |
This function gets the default logging handler for log messages
|
|
Packit |
3c2767 |
generated by contexts allocated with @code{assuan_new}.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
You do not need to set a log handler, as @sc{Assuan} provides a
|
|
Packit |
3c2767 |
configurable default log handler that should be suitable for most
|
|
Packit |
3c2767 |
purposes. Logging can be disabled completely by setting the log
|
|
Packit |
3c2767 |
handler to a null pointer.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Default Log Handler
|
|
Packit |
3c2767 |
@section Default Log Handler
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The default log handler can be configured by the following functions:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_set_assuan_log_prefix (@w{const char *@var{text}})
|
|
Packit |
3c2767 |
Set the prefix to be used at the start of a line emitted by assuan
|
|
Packit |
3c2767 |
on the log stream to @var{text}. The default is the empty string.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun @w{const char *} assuan_get_assuan_log_prefix (void)
|
|
Packit |
3c2767 |
Return the prefix to be used at the start of a line emitted by assuan
|
|
Packit |
3c2767 |
on the log stream. The default implementation returns the empty
|
|
Packit |
3c2767 |
string.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_set_assuan_log_stream (FILE *@var{fp})
|
|
Packit |
3c2767 |
This sets the default log stream to which @code{libassuan} should log messages not
|
|
Packit |
3c2767 |
associated with a specific context to @var{fp}. The default is to log
|
|
Packit |
3c2767 |
to @code{stderr}. This default value is also changed by using
|
|
Packit |
3c2767 |
@code{assuan_set_log_stream} (to set a logging stream for a specific
|
|
Packit |
3c2767 |
context) unless this function has been used. Obviously this is not
|
|
Packit |
3c2767 |
thread-safe and thus it is highly recommended to use this function to
|
|
Packit |
3c2767 |
setup a proper default.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun @w{FILE *} assuan_get_assuan_log_stream (void)
|
|
Packit |
3c2767 |
Return the stream which is currently being using for global logging.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The log stream used by the default log handler can also be set on a
|
|
Packit |
3c2767 |
per context basis.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_set_log_stream (@w{assuan_context_t @var{ctx}}, @w{FILE *@var{fp}})
|
|
Packit |
3c2767 |
Enable debugging for the context @var{ctx} and write all debugging
|
|
Packit |
3c2767 |
output to the stdio stream @var{fp}. If the default log stream (used
|
|
Packit |
3c2767 |
for non-context specific events) has not yet been set, a call to this
|
|
Packit |
3c2767 |
functions implicitly sets this stream also to @var{fp}.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Contexts
|
|
Packit |
3c2767 |
@section How to work with contexts
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Some operations work globally on the library, but most operate in a
|
|
Packit |
3c2767 |
context, which saves state across operations. To allow the use of
|
|
Packit |
3c2767 |
@code{libassuan} in mixed environments, such as in a library using
|
|
Packit |
3c2767 |
GPGME and an application using GPGME, the context is very extensive
|
|
Packit |
3c2767 |
and covers utilitary information like memory allocation callbacks as
|
|
Packit |
3c2767 |
well as specific information associated with client/server operations.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@anchor{function assuan_new}
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_new (@w{assuan_context_t *@var{ctx_p}})
|
|
Packit |
3c2767 |
The function @code{assuan_new} creates a new context, using the global
|
|
Packit |
3c2767 |
default memory allocation, log handler and @code{libgpg-error} source.
|
|
Packit |
3c2767 |
It is equivalent to
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@smallexample
|
|
Packit |
3c2767 |
gpg_error_t err;
|
|
Packit |
3c2767 |
assuan_log_cb_t log_cb;
|
|
Packit |
3c2767 |
void *log_cb_data;
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
assuan_get_log_cb (&log_cb, &log_cb_data);
|
|
Packit |
3c2767 |
err = assuan_new_ext (ctx_p, assuan_get_gpg_err_source (),
|
|
Packit |
3c2767 |
assuan_get_malloc_hooks (), log_cb, log_cb_data);
|
|
Packit |
3c2767 |
@end smallexample
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
As you can see, this is not thread-safe. Take care not to modify the
|
|
Packit |
3c2767 |
memory allocation hooks or log callback handler concurrently with
|
|
Packit |
3c2767 |
@code{assuan_new}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The function returns an error if a memory allocation error occurs, and
|
|
Packit |
3c2767 |
0 with the new context in @var{ctx_p} otherwise.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_new_ext (@w{assuan_context_t *@var{ctx_p}}, @w{gpg_err_source_t @var{err_source}}, @w{assuan_malloc_hooks_t @var{malloc_hooks}}, @w{assuan_log_cb_t @var{log_cb}}, @w{void *@var{log_cb_data}})
|
|
Packit |
3c2767 |
The function @code{assuan_new_ext} creates a new context using the
|
|
Packit |
3c2767 |
supplied @code{libgpg-error} error source @var{err_source}, the memory
|
|
Packit |
3c2767 |
allocation hooks @var{malloc_hooks} and the log handler @var{log_cb}
|
|
Packit |
3c2767 |
with the user data @var{log_cb_data}.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
After the context has been used, it can be destroyed again.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_release (assuan_context_t ctx)
|
|
Packit |
3c2767 |
The function @code{assuan_release} destroys the context CTX and
|
|
Packit |
3c2767 |
releases all associated resources.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Other properties of the context beside the memory allocation handler,
|
|
Packit |
3c2767 |
the log handler, and the @code{libgpg-error} source can be set after
|
|
Packit |
3c2767 |
context creation. Here are some of them:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_set_pointer (@w{assuan_context_t @var{ctx}}, @w{void *@var{pointer}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Store the arbitrary pointer value @var{pointer} into the context
|
|
Packit |
3c2767 |
@var{ctx}. This is useful to provide command handlers with additional
|
|
Packit |
3c2767 |
application context.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void* assuan_get_pointer (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This returns the pointer for context @var{ctx} which has been set using
|
|
Packit |
3c2767 |
the above function. A common way to use it is by setting the pointer
|
|
Packit |
3c2767 |
before starting the processing loop and to retrieve it right at the
|
|
Packit |
3c2767 |
start of a command handler:
|
|
Packit |
3c2767 |
@smallexample
|
|
Packit |
3c2767 |
static int
|
|
Packit |
3c2767 |
cmd_foo (assuan_context_t ctx, char *line)
|
|
Packit |
3c2767 |
@{
|
|
Packit |
3c2767 |
ctrl_t ctrl = assuan_get_pointer (ctx);
|
|
Packit |
3c2767 |
...
|
|
Packit |
3c2767 |
@}
|
|
Packit |
3c2767 |
@end smallexample
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_set_flag (@w{assuan_context_t @var{ctx}}, @w{assuan_flag_t @var{flag}}, @w{int @var{value}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Set the the @var{flag} for context @var{ctx} to @var{value}. Values for
|
|
Packit |
3c2767 |
flags are usually 1 or 0 but certain flags might need other values.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftp {Data type} assuan_flag_t
|
|
Packit |
3c2767 |
The flags are all named and collected in an @code{enum} for better readability.
|
|
Packit |
3c2767 |
Available flags are:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item ASSUAN_NO_WAITPID
|
|
Packit |
3c2767 |
When using a pipe server, by default Libassuan will wait for the forked
|
|
Packit |
3c2767 |
process to die in @code{assuan_release}. In certain cases this is
|
|
Packit |
3c2767 |
not desirable. By setting this flag, a call to @code{waitpid} will be
|
|
Packit |
3c2767 |
suppressed and the caller is responsible to cleanup the child process.
|
|
Packit |
3c2767 |
@item ASSUAN_CONFIDENTIAL
|
|
Packit |
3c2767 |
Use to return the state of the confidential logging mode.
|
|
Packit |
3c2767 |
@item ASSUAN_NO_FIXSIGNALS
|
|
Packit |
3c2767 |
Do not modify signal handler for @code{SIGPIPE}.
|
|
Packit |
3c2767 |
@item ASSUAN_CONVEY_COMMENTS
|
|
Packit |
3c2767 |
If enabled comment lines are passed to the status callback of the
|
|
Packit |
3c2767 |
@code{assuan_transact}.
|
|
Packit |
3c2767 |
@item ASSUAN_FORCE_CLOSE
|
|
Packit |
3c2767 |
Setting this flag forces the next command to assume that the
|
|
Packit |
3c2767 |
connection has been closed. This breaks the command processing loop
|
|
Packit |
3c2767 |
and may be used as an implicit BYE command. @var{value} is ignored
|
|
Packit |
3c2767 |
and thus it is not possible to clear this flag.
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
@end deftp
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun int assuan_get_flag (@w{assuan_context_t @var{ctx}}, @w{assuan_flag_t @var{flag}})
|
|
Packit |
3c2767 |
Return the value of @var{flag} in context @var{ctx}.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_begin_confidential (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
Put the logging feature into confidential mode. This is to avoid
|
|
Packit |
3c2767 |
logging of sensitive data.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This is identical to:
|
|
Packit |
3c2767 |
@smallexample
|
|
Packit |
3c2767 |
assuan_set_flag (ctx, ASSUAN_CONFIDENTIAL, 1);
|
|
Packit |
3c2767 |
@end smallexample
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_end_confidential (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
Get the logging feature out of confidential mode. All data will be
|
|
Packit |
3c2767 |
logged again (if logging is enabled).
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This is identical to:
|
|
Packit |
3c2767 |
@smallexample
|
|
Packit |
3c2767 |
assuan_set_flag (ctx, ASSUAN_CONFIDENTIAL, 0);
|
|
Packit |
3c2767 |
@end smallexample
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftp {Data type} {struct assuan_system_hooks}
|
|
Packit |
3c2767 |
This structure is used to store the system callback interface
|
|
Packit |
3c2767 |
functions. It has the following members, whose semantics are similar
|
|
Packit |
3c2767 |
to the corresponding system functions, but not exactly equivalent.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item int version
|
|
Packit |
3c2767 |
The user should set this to @code{ASSUAN_SYSTEM_HOOKS_VERSION}. This
|
|
Packit |
3c2767 |
indicates to the library which members of this structure are present
|
|
Packit |
3c2767 |
in case of future extensions. The user should initialize the whole
|
|
Packit |
3c2767 |
structure with zero bytes.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item void (*usleep) (assuan_context_t ctx, unsigned int usec)
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to sleep for @code{USEC}
|
|
Packit |
3c2767 |
microseconds.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item int (*pipe) (assuan_context_t ctx, assuan_fd_t fd[2], int inherit_idx)
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to create a pipe. The
|
|
Packit |
3c2767 |
returned file descriptor @code{fd[inherit_idx]} must be inheritable by
|
|
Packit |
3c2767 |
the child process (under Windows, this requires some extra work).
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item int (*close) (assuan_context_t ctx, assuan_fd_t fd)
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to close a file descriptor
|
|
Packit |
3c2767 |
created through the system functions.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item ssize_t (*read) (assuan_context_t ctx, assuan_fd_t fd, void *buffer, size_t size)
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to read data from a file
|
|
Packit |
3c2767 |
descriptor. It is functionally equivalent to the system @code{read}
|
|
Packit |
3c2767 |
function.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item ssize_t (*write) (assuan_context_t ctx, assuan_fd_t fd, const void *buffer, size_t size)
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to write data to a file
|
|
Packit |
3c2767 |
descriptor. It is functionally equivalent to the system @code{write}
|
|
Packit |
3c2767 |
function.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item int (*recvmsg) (assuan_context_t ctx, assuan_fd_t fd, assuan_msghdr_t msg, int flags)
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to receive a message from a
|
|
Packit |
3c2767 |
file descriptor. It is functionally equivalent to the system
|
|
Packit |
3c2767 |
@code{recvmsg} function.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item int (*sendmsg) (assuan_context_t ctx, assuan_fd_t fd, const assuan_msghdr_t msg, int flags);
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to send a message to a
|
|
Packit |
3c2767 |
file descriptor. It is functionally equivalent to the system
|
|
Packit |
3c2767 |
@code{sendmsg} function.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item 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)
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to spawn a child process.
|
|
Packit |
3c2767 |
The @code{stdin} and @code{stdout} file descriptors are provided in
|
|
Packit |
3c2767 |
@code{fd_in} and @code{fd_out} respectively, but can be set to
|
|
Packit |
3c2767 |
@code{ASSUAN_INVALID_FD}, in which case they are set to
|
|
Packit |
3c2767 |
@code{/dev/null}. On systems which use @code{fork} and @code{exec},
|
|
Packit |
3c2767 |
the @code{atfork} function should be called with @code{atforkvalue}
|
|
Packit |
3c2767 |
and @code{0} for flags in the child process right after @code{fork}
|
|
Packit |
3c2767 |
returns. @code{fd_child_list} is a @code{ASSUAN_INVALID_FD}
|
|
Packit |
3c2767 |
terminated array (or @code{NULL}) and specifies file descriptors to be
|
|
Packit |
3c2767 |
inherited by the child process.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
A special situation occurs if @code{name} is a null pointer, in which
|
|
Packit |
3c2767 |
case the process should just fork but not call @code{exec}. In this
|
|
Packit |
3c2767 |
case, @code{*argv} should be set to @code{"client"} in the parent
|
|
Packit |
3c2767 |
process and @code{"server"} in the child process.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Flags is the bit-wise OR of some (or none) of the following flags:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item ASSUAN_SPAWN_DETACHED
|
|
Packit |
3c2767 |
If set and there is a need to start the server it will be started as a
|
|
Packit |
3c2767 |
background process. This flag is useful under W32 systems, so that no
|
|
Packit |
3c2767 |
new console is created and pops up a console window when starting the
|
|
Packit |
3c2767 |
server. On W32CE systems this flag is ignored.
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item pid_t (*waitpid) (assuan_context_t ctx, pid_t pid, int action, int *status, int options)
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to wait for the spawned
|
|
Packit |
3c2767 |
child process @var{pid} to exit, or, if @var{action} is 1, to just
|
|
Packit |
3c2767 |
release all resources associated with @var{pid} (required on Windows
|
|
Packit |
3c2767 |
platforms). If @var{action} is 0, this is equivalent to @code{waitpid}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item int (*socketpair) (assuan_context_t ctx, int namespace, int style, int protocol, assuan_fd_t filedes[2])
|
|
Packit |
3c2767 |
This is the function called by @sc{Assuan} to create a socketpair. It
|
|
Packit |
3c2767 |
is equivalent to @code{socketpair}.
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
@end deftp
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_set_system_hooks (@w{assuan_system_hooks_t @var{system_hooks}})
|
|
Packit |
3c2767 |
Set the default system hooks to use. There is currently no way to
|
|
Packit |
3c2767 |
reset to the default system hooks.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_sock_set_system_hooks (@w{assuan_system_hooks_t @var{system_hooks}})
|
|
Packit |
3c2767 |
The socket subsystem uses an internal context which uses the default
|
|
Packit |
3c2767 |
system hooks. This function allows to change these system hooks. The
|
|
Packit |
3c2767 |
function is not thread-safe and only useful if a certain order of
|
|
Packit |
3c2767 |
assuan and assuan socket initializations are required.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_ctx_set_system_hooks (@w{assuan_context_t @var{ctx}}, @w{assuan_system_hooks_t @var{system_hooks}})
|
|
Packit |
3c2767 |
Set the system hooks for context @var{ctx}. There is currently no way
|
|
Packit |
3c2767 |
to reset to the default system hooks, create a new context for that.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The following system hook collections are defined by the library for
|
|
Packit |
3c2767 |
your convenience:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item ASSUAN_SYSTEM_NPTH
|
|
Packit |
3c2767 |
System hooks suitable for use with the nPth library.
|
|
Packit |
3c2767 |
@item ASSUAN_SYSTEM_NPTH_IMPL
|
|
Packit |
3c2767 |
The implementation of system hooks for use with the nPth library.
|
|
Packit |
3c2767 |
This must be invoked once somewhere in the application, and defines
|
|
Packit |
3c2767 |
the structure that is referenced by @code{ASSUAN_SYSTEM_NPTH}.
|
|
Packit |
3c2767 |
@item ASSUAN_SYSTEM_PTH
|
|
Packit |
3c2767 |
System hooks suitable for use with the GNU Pth library.
|
|
Packit |
3c2767 |
@item ASSUAN_SYSTEM_PTH_IMPL
|
|
Packit |
3c2767 |
The implementation of system hooks for use with the GNU Pth library.
|
|
Packit |
3c2767 |
This must be invoked once somewhere in the application, and defines
|
|
Packit |
3c2767 |
the structure that is referenced by @code{ASSUAN_SYSTEM_PTH}.
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Reading and Writing
|
|
Packit |
3c2767 |
@section How to communicate with the peer
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
What would be an IPC library without the ability to read and write
|
|
Packit |
3c2767 |
data? Not very useful. Libassuan has high level functions to take
|
|
Packit |
3c2767 |
care of of the more boring stuff, but eventually data needs to be
|
|
Packit |
3c2767 |
written and read.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
The basic read and write functions are:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_read_line (@w{assuan_context_t @var{ctx}}, @w{char **@var{line}}, @w{size_t *@var{linelen}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Read the next line written by the peer to the control channel and store
|
|
Packit |
3c2767 |
a pointer to the buffer holding that line at the address @var{line}.
|
|
Packit |
3c2767 |
The valid length of the lines is stored at the address of @var{linelen}.
|
|
Packit |
3c2767 |
This buffer is valid until the next read operation on the same context
|
|
Packit |
3c2767 |
@var{ctx}. You may modify the context of this buffer. The buffer is
|
|
Packit |
3c2767 |
invalid (i.e. must not be used) if an error is returned. This function
|
|
Packit |
3c2767 |
returns @code{0} on success or an error value.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_write_line (@w{assuan_context_t @var{ctx}}, @w{const char *@var{line}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Write the string @var{line} to the other end on the control channel.
|
|
Packit |
3c2767 |
This string needs to be a proper formatted Assuan protocol line and
|
|
Packit |
3c2767 |
should not include a linefeed. Sending linefeed or @code{Nul}
|
|
Packit |
3c2767 |
characters is not possible and not allowed by the assuan protocol. This
|
|
Packit |
3c2767 |
function shall not be used for sending data (@code{D}) lines. This
|
|
Packit |
3c2767 |
function returns @code{0} on success or an error value.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
To actually send bulk data lines a specialized function is available:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_send_data (@w{assuan_context_t @var{ctx}}, @w{const void *@var{buffer}}, @w{size_t @var{length}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This function is used by a server or a client to send @var{length} bytes
|
|
Packit |
3c2767 |
of bulk data in @var{buffer} to the other end on the control channel.
|
|
Packit |
3c2767 |
The data will be escaped as required by the Assuan protocol and may get
|
|
Packit |
3c2767 |
buffered until a line is full. To flush any pending data, @var{buffer}
|
|
Packit |
3c2767 |
may be passed as @code{NULL} and @var{length} be @code{0}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
When used by a client, this flush operation does also send the
|
|
Packit |
3c2767 |
@code{END} command to terminate the response on an @command{INQUIRE}
|
|
Packit |
3c2767 |
request. Note that the function @code{assuan_transact} takes care of
|
|
Packit |
3c2767 |
sending this @code{END} itself.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
This function returns @code{0} on success or an error value.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The input and output of data can be controlled at a higher level using
|
|
Packit |
3c2767 |
an I/O monitor.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftp {Data type} {unsigned int (*assuan_io_monitor_t) (@w{assuan_context_t @var{ctx}}, @w{void *@var{hook_value}}, @w{int @var{inout}}, @w{const char *@var{line}}, @w{size_t @var{linelen}})}
|
|
Packit |
3c2767 |
The monitor function is called right after a line has been received,
|
|
Packit |
3c2767 |
if @var{inout} is @code{ASSUAN_IO_FROM_PEER}, or just before it is
|
|
Packit |
3c2767 |
send, if @var{inout} is @code{ASSUAN_IO_TO_PEER}. The
|
|
Packit |
3c2767 |
@var{hook_value} is provided by the user when registering the I/O
|
|
Packit |
3c2767 |
monitor function with a context using @code{assuan_set_io_monitor}.
|
|
Packit |
3c2767 |
The callback function should return the bitwise OR of some (or none) of the
|
|
Packit |
3c2767 |
following flags:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item ASSUAN_IO_MONITOR_NOLOG
|
|
Packit |
3c2767 |
Active logging of this line is suppressed. This can reduce debug
|
|
Packit |
3c2767 |
output in the case of a frequent message.
|
|
Packit |
3c2767 |
@item ASSUAN_IO_MONITOR_IGNORE
|
|
Packit |
3c2767 |
The whole output line is discarded.
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
@end deftp
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_set_io_monitor (@w{assuan_context_t @var{ctx}}, @w{assuan_io_monitor_t @var{io_monitor}}, @w{void *@var{hook_data}})
|
|
Packit |
3c2767 |
This function registers an I/O monitor @var{io_monitor} for the
|
|
Packit |
3c2767 |
context @var{ctx} with the hook value @var{hook_data}.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@c C L I E N T C O D E
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@node Client code
|
|
Packit |
3c2767 |
@chapter How to develop an Assuan client
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Depending on the type of the server you want to connect you need to use
|
|
Packit |
3c2767 |
different functions.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
If the peer is not a simple pipe server but one using full-duplex
|
|
Packit |
3c2767 |
sockets, the full-fledged variant of the above function should be
|
|
Packit |
3c2767 |
used:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_pipe_connect (@w{assuan_context_t @var{ctx}},@w{const char *@var{name}}, @w{const char *@var{argv}[]}, @w{assuan_fd_t *@var{fd_child_list}}, @w{void (*@var{atfork}) (void *, int)}, @w{void *@var{atforkvalue}}, @w{unsigned int @var{flags}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
A call to this functions forks the current process and executes the
|
|
Packit |
3c2767 |
program @var{name}, passing the arguments given in the NULL-terminated
|
|
Packit |
3c2767 |
list @var{argv}. A list of file descriptors not to be closed may be
|
|
Packit |
3c2767 |
given using the @code{ASSUAN_INVALID_FD} terminated array @var{fd_child_list}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
If @var{name} is a null pointer, only a fork but no exec is done. Thus
|
|
Packit |
3c2767 |
the child continues to run. However all file descriptors are closed and
|
|
Packit |
3c2767 |
some special environment variables are set. To let the caller detect
|
|
Packit |
3c2767 |
whether the child or the parent continues, the parent returns with
|
|
Packit |
3c2767 |
@code{"client"} returned in @var{argv} and the child returns with
|
|
Packit |
3c2767 |
@code{"server"} in @var{argv}. This feature is only available on POSIX
|
|
Packit |
3c2767 |
platforms.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
If @var{atfork} is not NULL, this function is called in the child right
|
|
Packit |
3c2767 |
after the fork and the value @var{atforkvalue} is passed as the first
|
|
Packit |
3c2767 |
argument. That function should only act if the second argument it
|
|
Packit |
3c2767 |
received is @code{0}. Such a fork callback is useful to release
|
|
Packit |
3c2767 |
additional resources not to be used by the child.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
@var{flags} is a bit vector and controls how the function acts:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item ASSUAN_PIPE_CONNECT_FDPASSING
|
|
Packit |
3c2767 |
If cleared a simple pipe based server is expected. If set a server
|
|
Packit |
3c2767 |
based on full-duplex pipes is expected. Such pipes are usually
|
|
Packit |
3c2767 |
created using the @code{socketpair} function. It also enables
|
|
Packit |
3c2767 |
features only available with such servers.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item ASSUAN_PIPE_CONNECT_DETACHED
|
|
Packit |
3c2767 |
If set and there is a need to start the server it will be started as a
|
|
Packit |
3c2767 |
background process. This flag is useful under W32 systems, so that no
|
|
Packit |
3c2767 |
new console is created and pops up a console window when starting the
|
|
Packit |
3c2767 |
server. On W32CE systems this flag is ignored.
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
If you are using a long running server listening either on a TCP or a
|
|
Packit |
3c2767 |
Unix domain socket, the following function is used to connect to the server:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_socket_connect (@w{assuan_context_t @var{ctx}}, @w{const char *@var{name}}, @w{pid_t @var{server_pid}}, @w{unsigned int @var{flags}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Make a connection to the Unix domain socket @var{name} using the
|
|
Packit |
3c2767 |
already-initialized Assuan context at @var{ctx}. @var{server_pid} is
|
|
Packit |
3c2767 |
currently not used but may become handy in the future; if you don't
|
|
Packit |
3c2767 |
know the server's process ID (PID), pass @code{ASSUAN_INVALID_PID}.
|
|
Packit |
3c2767 |
With @var{flags} set to @code{ASSUAN_SOCKET_CONNECT_FDPASSING},
|
|
Packit |
3c2767 |
@code{sendmsg} and @code{recvmesg} are used for input and output and
|
|
Packit |
3c2767 |
thereby enable the use of descriptor passing.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Connecting to a TCP server is not yet implemented. Standard URL
|
|
Packit |
3c2767 |
schemes are reserved for @var{name} specifying a TCP server.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Now that we have a connection to the server, all work may be
|
|
Packit |
3c2767 |
conveniently done using a couple of callbacks and the transact
|
|
Packit |
3c2767 |
function:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_transact (@w{assuan_context_t @var{ctx}}, @w{const char *@var{command}}, @w{gpg_error_t (*@var{data_cb})(void *, const void *, size_t)}, @w{void *@var{data_cb_arg}}, @w{gpg_error_t (*@var{inquire_cb})(void*, const char *)}, @w{void *@var{inquire_cb_arg}}, @w{gpg_error_t (*@var{status_cb})(void*, const char *)}, @w{void *@var{status_cb_arg}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Here @var{ctx} is the Assuan context opened by one of the connect
|
|
Packit |
3c2767 |
calls. @var{command} is the actual Assuan command string. It
|
|
Packit |
3c2767 |
shall not end with a line feed and its length is limited to
|
|
Packit |
3c2767 |
@code{ASSUAN_LINELENGTH} (~1000 bytes)
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@var{data_cb} is called by Libassuan for data lines; @var{data_cb_arg}
|
|
Packit |
3c2767 |
is passed to it along with the data and the length. [FIXME: needs
|
|
Packit |
3c2767 |
more documentation].
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@var{inquire_cb} is called by Libassuan when the server requests
|
|
Packit |
3c2767 |
additional information from the client while processing the command.
|
|
Packit |
3c2767 |
This callback shall check the provided inquiry name and send the data
|
|
Packit |
3c2767 |
as requested back using the @code{assuan_send_data}. The server
|
|
Packit |
3c2767 |
passed @var{inquiry_cb_arg} along with the inquiry name to the
|
|
Packit |
3c2767 |
callback.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@var{status_cb} is called by Libassuan for each status line it receives
|
|
Packit |
3c2767 |
from the server. @var{status_cb_arg} is passed along with the status
|
|
Packit |
3c2767 |
line to the callback.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The function returns @code{0} success or an error value. The error value
|
|
Packit |
3c2767 |
may be the one one returned by the server in error lines or one
|
|
Packit |
3c2767 |
generated by the callback functions.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Libassuan supports descriptor passing on some platforms. The next two
|
|
Packit |
3c2767 |
functions are used with this feature:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@anchor{function assuan_sendfd}
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_sendfd (@w{assuan_context_t @var{ctx}}, @w{assuan_fd_t @var{fd}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Send the descriptor @var{fd} to the peer using the context @var{ctx}.
|
|
Packit |
3c2767 |
The descriptor must be sent before the command is issued that makes
|
|
Packit |
3c2767 |
use of the descriptor.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Note that calling this function with a @var{ctx} of @code{NULL} and
|
|
Packit |
3c2767 |
@var{fd} of @code{ASSUAN_INVALID_FD} can be used as a runtime test to
|
|
Packit |
3c2767 |
check whether descriptor passing is available on the platform:
|
|
Packit |
3c2767 |
@code{0} is returned if descriptor passing is available, otherwise an
|
|
Packit |
3c2767 |
error with the error code @code{GPG_ERR_NOT_IMPLEMENTED} is returned.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@anchor{function assuan_receivefd}
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_receivefd (@w{assuan_context_t @var{ctx}}, @w{assuan_fd_t *@var{fd}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Receive a descriptor pending for the context @var{ctx} from the peer.
|
|
Packit |
3c2767 |
The descriptor must be pending before this function is called. To
|
|
Packit |
3c2767 |
accomplish this, the peer needs to use @code{assuan_sendfd} before the
|
|
Packit |
3c2767 |
trigger is sent (e.g. using @code{assuan_write_line ("INPUT FD")}.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@c S E R V E R C O D E
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@node Server code
|
|
Packit |
3c2767 |
@chapter How to develop an Assuan server
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Implementing a server for Assuan is a bit more complex than a client.
|
|
Packit |
3c2767 |
However, it is a straightforward task we are going to explain using a
|
|
Packit |
3c2767 |
commented example.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
The list of the implemented server commands is defined by a table like:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@smallexample
|
|
Packit |
3c2767 |
static struct @{
|
|
Packit |
3c2767 |
const char *name;
|
|
Packit |
3c2767 |
int (*handler) (assuan_context_t, char *line);
|
|
Packit |
3c2767 |
@} command_table[] = @{
|
|
Packit |
3c2767 |
@{ "FOO", cmd_foo @},
|
|
Packit |
3c2767 |
@{ "BAR", cmd_bar @},
|
|
Packit |
3c2767 |
@{ "INPUT", NULL @},
|
|
Packit |
3c2767 |
@{ "OUTPUT", NULL @},
|
|
Packit |
3c2767 |
@{ NULL @}@};
|
|
Packit |
3c2767 |
@end smallexample
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
For convenience this table is usually put after the actual command
|
|
Packit |
3c2767 |
handlers (@code{cmd_foo}, @code{cmd_bar}) or even put inside
|
|
Packit |
3c2767 |
@code{command_handler} (see below). Note that the commands
|
|
Packit |
3c2767 |
@code{INPUT} and @code{OUTPUT} do not require a handler because
|
|
Packit |
3c2767 |
Libassuan provides a default handler for them. It is however possible
|
|
Packit |
3c2767 |
to assign a custom handler.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
A prerequisite for this example code is that a client has already
|
|
Packit |
3c2767 |
connected to the server. Often there are two modes combined in one
|
|
Packit |
3c2767 |
program: A pipe-based server, where a client has forked the server
|
|
Packit |
3c2767 |
process, or a Unix domain socket based server that is listening on the
|
|
Packit |
3c2767 |
socket.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
void
|
|
Packit |
3c2767 |
command_handler (int fd)
|
|
Packit |
3c2767 |
@{
|
|
Packit |
3c2767 |
gpg_error_t rc;
|
|
Packit |
3c2767 |
int i;
|
|
Packit |
3c2767 |
assuan_context_t ctx;
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
rc = assuan_new (&ctx;;
|
|
Packit |
3c2767 |
if (rc)
|
|
Packit |
3c2767 |
@{
|
|
Packit |
3c2767 |
fprintf (stderr, "server context creation failed: %s\n",
|
|
Packit |
3c2767 |
gpg_strerror(rc));
|
|
Packit |
3c2767 |
return;
|
|
Packit |
3c2767 |
@}
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
if (fd == -1)
|
|
Packit |
3c2767 |
@{
|
|
Packit |
3c2767 |
assuan_fd_t filedes[2];
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
filedes[0] = assuan_fd_from_posix_fd (0);
|
|
Packit |
3c2767 |
filedes[1] = assuan_fd_from_posix_fd (1);
|
|
Packit |
3c2767 |
rc = assuan_init_pipe_server (ctx, filedes);
|
|
Packit |
3c2767 |
@}
|
|
Packit |
3c2767 |
else
|
|
Packit |
3c2767 |
rc = assuan_init_socket_server (ctx, fd, ASSUAN_SOCKET_SERVER_ACCEPTED);
|
|
Packit |
3c2767 |
if (rc)
|
|
Packit |
3c2767 |
@{
|
|
Packit |
3c2767 |
fprintf (stderr, "server init failed: %s\n", gpg_strerror (rc));
|
|
Packit |
3c2767 |
return;
|
|
Packit |
3c2767 |
@}
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
This is the first part of the command handler. We start off by
|
|
Packit |
3c2767 |
allocating a new Assuan context with @code{assuan_new}.
|
|
Packit |
3c2767 |
@xref{function assuan_new}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
In case this is called as a pipe based server, @var{fd} will be based
|
|
Packit |
3c2767 |
as @var{fd} and the code assumes that the server's @code{stdin} and
|
|
Packit |
3c2767 |
@code{stdout} file handles are connected to a pipe. The
|
|
Packit |
3c2767 |
initialization is thus done using the function:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_init_pipe_server (@w{assuan_context_t @var{ctx}}, @w{assuan_fd_t @var{filedes}[2]})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This function takes the two file descriptors from @var{filedes} and
|
|
Packit |
3c2767 |
returns a new Assuan context at @var{r_ctx}. As usual, a return value
|
|
Packit |
3c2767 |
of @code{0} indicates success and a failure is indicated by
|
|
Packit |
3c2767 |
returning an error value. In case of error, @code{NULL} will be stored
|
|
Packit |
3c2767 |
at @var{r_ctx}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
In case the server has been called using a bi-directional pipe
|
|
Packit |
3c2767 |
(socketpair), @var{filedes} is ignored and the file descriptor is
|
|
Packit |
3c2767 |
taken from the environment variable @env{_assuan_connection_fd}. You
|
|
Packit |
3c2767 |
generally don't need to know this, because @code{assuan_pipe_connect},
|
|
Packit |
3c2767 |
which is called by the client to connect to such a server,
|
|
Packit |
3c2767 |
automagically sets this variable.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_init_socket_server (@w{assuan_context_t @var{ctx}}, @w{assuan_fd_t @var{fd}}, @w{unsigned int @var{flags}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This function takes the file descriptor @var{fd}, which is expected to
|
|
Packit |
3c2767 |
be associated with a socket, and an Assuan context @var{ctx}. The
|
|
Packit |
3c2767 |
following bits are currently defined for @var{flags}:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item ASSUAN_SOCKET_SERVER_FDPASSING
|
|
Packit |
3c2767 |
If set, @code{sendmsg} and @code{recvmesg} are used for input and
|
|
Packit |
3c2767 |
output, which enables the use of descriptor passing.
|
|
Packit |
3c2767 |
@item ASSUAN_SOCKET_SERVER_ACCEPTED
|
|
Packit |
3c2767 |
If set, @var{fd} refers to an already accepted socket. That is,
|
|
Packit |
3c2767 |
Libassuan won't call @var{accept} for it. It is suggested to set this
|
|
Packit |
3c2767 |
bit as it allows better control of the connection state.
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
As usual, a return value of @code{0} indicates success and a failure
|
|
Packit |
3c2767 |
is indicated by returning an error value.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
On the Windows platform the following function needs to be called after
|
|
Packit |
3c2767 |
@code{assuan_init_socket_server}:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun void assuan_set_sock_nonce ( @
|
|
Packit |
3c2767 |
@w{assuan_context_t @var{ctx}}, @
|
|
Packit |
3c2767 |
@w{assuan_sock_nonce_t *@var{nonce}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Save a copy of @var{nonce} in context @var{ctx}. This should be used
|
|
Packit |
3c2767 |
to register the server's nonce with a context established by
|
|
Packit |
3c2767 |
@code{assuan_init_socket_server}. It is technically only needed for
|
|
Packit |
3c2767 |
Windows, but it does no harm to use it on other systems.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
After error checking, the implemented assuan commands are registered with
|
|
Packit |
3c2767 |
the server.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
for (i = 0; command_table[i].name; i++)
|
|
Packit |
3c2767 |
@{
|
|
Packit |
3c2767 |
rc = assuan_register_command (ctx,
|
|
Packit |
3c2767 |
command_table[i].name,
|
|
Packit |
3c2767 |
command_table[i].handler, NULL);
|
|
Packit |
3c2767 |
if (rc)
|
|
Packit |
3c2767 |
@{
|
|
Packit |
3c2767 |
fprintf (stderr, "register failed: %s\n", gpg_strerror (rc));
|
|
Packit |
3c2767 |
assuan_release (ctx);
|
|
Packit |
3c2767 |
return;
|
|
Packit |
3c2767 |
@}
|
|
Packit |
3c2767 |
@}
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftp {Data type} {gpg_error_t (*assuan_handler_t) (@w{assuan_context_t @var{ctx}}, @w{char *@var{line}})}
|
|
Packit |
3c2767 |
This is the function invoked by @sc{Assuan} for various command
|
|
Packit |
3c2767 |
related callback functions. Some of these callback functions have a
|
|
Packit |
3c2767 |
different type, but most use @code{assuan_handler_t}.
|
|
Packit |
3c2767 |
@end deftp
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_register_command (@w{assuan_context_t @var{ctx}}, @w{const char *@var{cmd_string}}, @w{assuan_handler_t @var{handler}}, @w{const char *@var{help_string}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This registers the command named @var{cmd_string} with the Assuan
|
|
Packit |
3c2767 |
context @var{ctx}. @var{handler} is the function called by Libassuan
|
|
Packit |
3c2767 |
if this command is received from the client. @var{NULL} may be used
|
|
Packit |
3c2767 |
for @var{handler} to use a default handler (this only works with a few
|
|
Packit |
3c2767 |
pre-defined commands). Note that several default handlers have
|
|
Packit |
3c2767 |
already been registered when the context has been created: @code{NOP},
|
|
Packit |
3c2767 |
@code{CANCEL}, @code{OPTION}, @code{BYE}, @code{AUTH}, @code{RESET}
|
|
Packit |
3c2767 |
and @code{END}. It is possible, but not recommended, to override
|
|
Packit |
3c2767 |
these commands.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@var{help_string} is a help string that is used for automatic
|
|
Packit |
3c2767 |
documentation. It should contain a usage line followed by an empty
|
|
Packit |
3c2767 |
line and a complete description.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_register_post_cmd_notify (@w{assuan_context_t @var{ctx}}, @w{void (*@var{fnc})(assuan_context_t)}, @w{gpg_error_t @var{err}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Register a function to be called right after a command has been
|
|
Packit |
3c2767 |
processed. @var{err} is the result code from the last internal assuan
|
|
Packit |
3c2767 |
operation and not the one returned by the handler. It may be used for
|
|
Packit |
3c2767 |
command-related cleanup.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_register_bye_notify (@w{assuan_context_t @var{ctx}}, @w{assuan_handler_t @var{handler}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Register function @var{fnc} with context @var{ctx} to be called right
|
|
Packit |
3c2767 |
before the standard handler for the @code{BYE} command is being called.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_register_reset_notify (@w{assuan_context_t @var{ctx}}, @w{assuan_handler_t @var{handler}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Register function @var{fnc} with context @var{ctx} to be called right
|
|
Packit |
3c2767 |
before the standard handler for the @code{RESET} command is being called.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_register_cancel_notify (@w{assuan_context_t @var{ctx}}, @w{assuan_handler_t @var{handler}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Register function @var{fnc} with context @var{ctx} to be called right
|
|
Packit |
3c2767 |
before the standard handler for the @code{RESET} command is being called.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_register_option_handler (@w{assuan_context_t @var{ctx}}, @w{gpg_error_t (*@var{fnc})(assuan_context_t, const char*, const char*)})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Register function @var{fnc} with context @var{ctx} for processing
|
|
Packit |
3c2767 |
options. That function is being called with the context, the name and
|
|
Packit |
3c2767 |
the value of the option. Leading and trailing spaces are removed from
|
|
Packit |
3c2767 |
the name and the value. The optional leading two dashes of the name
|
|
Packit |
3c2767 |
are removed as well. If no value has been given, an empty string is
|
|
Packit |
3c2767 |
passed. The function needs to return @code{0} on success or an error
|
|
Packit |
3c2767 |
code.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_register_input_notify (@w{assuan_context_t @var{ctx}}, @w{assuan_handler_t @var{handler}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Although the input function may be overridden with a custom handler, it
|
|
Packit |
3c2767 |
is often more convenient to use the default handler and to know whether
|
|
Packit |
3c2767 |
an @code{INPUT} command has been seen and successfully parsed. The second
|
|
Packit |
3c2767 |
argument passed to that function is the entire line. Because that line
|
|
Packit |
3c2767 |
has already been parsed when the function gets called, a file descriptor
|
|
Packit |
3c2767 |
set with the @code{INPUT} command may already be used. That file
|
|
Packit |
3c2767 |
descriptor is available by calling @code{assuan_get_input_fd}. If the
|
|
Packit |
3c2767 |
notification function returns an error, the input fd does not change.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_register_output_notify (@w{assuan_context_t @var{ctx}}, @w{assuan_handler_t @var{handler}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Although the output function may be overridden with a custom handler, it
|
|
Packit |
3c2767 |
is often more convenient to use the default handler and to know whether
|
|
Packit |
3c2767 |
an @code{OUTPUT} command has been seen and successfully parsed. The second
|
|
Packit |
3c2767 |
argument passed to that function is the entire line. Because that line
|
|
Packit |
3c2767 |
has already been parsed when the function gets called, a file descriptor
|
|
Packit |
3c2767 |
set with the @code{OUTPUT} command may already be used. That file
|
|
Packit |
3c2767 |
descriptor is available by calling @code{assuan_get_output_fd}. If the
|
|
Packit |
3c2767 |
notification function returns an error, the output fd does not change.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_set_hello_line (@w{assuan_context_t @var{ctx}}, @w{const char *@var{line}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This is not actually a register function but may be called also after
|
|
Packit |
3c2767 |
registering commands. It changes the ``Hello'' line, sent by the
|
|
Packit |
3c2767 |
server to the client as a first response, from a default string to the
|
|
Packit |
3c2767 |
string @var{line}. For logging purposes, it is often useful to use
|
|
Packit |
3c2767 |
such a custom hello line which may tell version numbers and such.
|
|
Packit |
3c2767 |
Linefeeds are allowed in this string, however, each line needs to be
|
|
Packit |
3c2767 |
shorter than the Assuan line length limit.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
Now that everything has been setup, we can start to process our
|
|
Packit |
3c2767 |
clients requests.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
for (;;)
|
|
Packit |
3c2767 |
@{
|
|
Packit |
3c2767 |
rc = assuan_accept (ctx);
|
|
Packit |
3c2767 |
if (rc == -1)
|
|
Packit |
3c2767 |
break;
|
|
Packit |
3c2767 |
else if (rc)
|
|
Packit |
3c2767 |
@{
|
|
Packit |
3c2767 |
fprintf (stderr, "accept problem: %s\n", gpg_strerror (rc));
|
|
Packit |
3c2767 |
break;
|
|
Packit |
3c2767 |
@}
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
rc = assuan_process (ctx);
|
|
Packit |
3c2767 |
if (rc)
|
|
Packit |
3c2767 |
@{
|
|
Packit |
3c2767 |
fprintf (stderr, "processing failed: %s\n", gpg_strerror (rc));
|
|
Packit |
3c2767 |
continue;
|
|
Packit |
3c2767 |
@}
|
|
Packit |
3c2767 |
@}
|
|
Packit |
3c2767 |
assuan_release (ctx);
|
|
Packit |
3c2767 |
@}
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
For future extensibility and to properly detect the end of the
|
|
Packit |
3c2767 |
connection the core of the server should loop over the
|
|
Packit |
3c2767 |
accept and process calls.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_accept (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
A call to this function cancel any existing connection and waits for a
|
|
Packit |
3c2767 |
connection from a client (that might be skipped, depending on the type
|
|
Packit |
3c2767 |
of the server). The initial handshake is performed which may include an
|
|
Packit |
3c2767 |
initial authentication or encryption negotiation. On success @code{0}
|
|
Packit |
3c2767 |
is returned. An error value will be returned if the connection could for
|
|
Packit |
3c2767 |
some reason not be established. An error code of @code{GPG_ERR_EOF} indicates
|
|
Packit |
3c2767 |
the end of the connection.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_process (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This function is used to handle the Assuan protocol after a connection
|
|
Packit |
3c2767 |
has been established using @code{assuan_accept}. It is the main
|
|
Packit |
3c2767 |
protocol handler responsible for reading the client commands and calling
|
|
Packit |
3c2767 |
the appropriate handlers. The function returns @code{0} on success or
|
|
Packit |
3c2767 |
an error value if something went seriously wrong. Error values from the
|
|
Packit |
3c2767 |
individual command handlers, i.e. operational error, are not seen here.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
That is all needed for the server code. You only need to come up with
|
|
Packit |
3c2767 |
the code for the individual command handlers. Take care that the line
|
|
Packit |
3c2767 |
passed to the command handlers is allocated statically within the
|
|
Packit |
3c2767 |
context and calls to Assuan functions may modify that line. You are
|
|
Packit |
3c2767 |
also allowed to modify that line which makes parsing much easier.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@c E x t e r n a l I / O L o o p s
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@node External I/O Loop
|
|
Packit |
3c2767 |
@chapter How to use external I/O event loops
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The above implementations of an Assuan client and server are
|
|
Packit |
3c2767 |
synchronous, insofar as the main routines block until a request or
|
|
Packit |
3c2767 |
client connection is completely processed. In some programs, for
|
|
Packit |
3c2767 |
example GUI applications, this is undesirable. Instead, Assuan
|
|
Packit |
3c2767 |
operations should be non-blocking, and the caller should be able to
|
|
Packit |
3c2767 |
poll all involved file descriptors to determine when the next Assuan
|
|
Packit |
3c2767 |
function can be invoked without blocking.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
To make this possible, client and server have to adhere to some rules:
|
|
Packit |
3c2767 |
@itemize @bullet
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
Either partner should always write full lines. If partial lines are
|
|
Packit |
3c2767 |
written, the remainder of the line should be sent without delay.
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
Either partner should eagerly receive status messages. While
|
|
Packit |
3c2767 |
receiving and sending bulk data may be delayed, the status
|
|
Packit |
3c2767 |
communication channel is different: Both partners may send status
|
|
Packit |
3c2767 |
messages in blocking mode at any time the protocol allows them to send
|
|
Packit |
3c2767 |
such status messages. To ensure that these send operations do not
|
|
Packit |
3c2767 |
actually block the sender, the recipient must be ready to receive
|
|
Packit |
3c2767 |
without undue delay.
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
If descriptor passing is used over a socket, the descriptor must be
|
|
Packit |
3c2767 |
sent after the corresponding command without undue delay.
|
|
Packit |
3c2767 |
@end itemize
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Together, these restrictions allow to limit the need for asynchronous
|
|
Packit |
3c2767 |
I/O operations to bulk data and the inbound status file descriptor.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
In addition to the above rules, client and server should adhere to the
|
|
Packit |
3c2767 |
following implementation guidelines.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@menu
|
|
Packit |
3c2767 |
* External I/O Loop Client:: External I/O event loops in the client.
|
|
Packit |
3c2767 |
* External I/O Loop Server:: External I/O event loops in the server.
|
|
Packit |
3c2767 |
@end menu
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node External I/O Loop Client
|
|
Packit |
3c2767 |
@section External I/O event loops in the client.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The reference implementation for using external I/O event loops in the
|
|
Packit |
3c2767 |
client is the GPGME library, which exports its own external I/O event
|
|
Packit |
3c2767 |
loop mechanism and utilizes the Assuan library transparently for the
|
|
Packit |
3c2767 |
user. The following steps document how GPGME achieves this.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@enumerate
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
Before connecting, set up pipes for bulk data transfer (using the
|
|
Packit |
3c2767 |
INPUT/OUTPUT commands, for example). These are passed to the server
|
|
Packit |
3c2767 |
either by inheritance (using a pipe server) or by FD passing (using a
|
|
Packit |
3c2767 |
socket server).
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
Then you need to connect to the server. GPGME uses a pipe server, so
|
|
Packit |
3c2767 |
it just spawns a server process, which is a non-blocking operation.
|
|
Packit |
3c2767 |
FIXME: Currently, using a client with external event loop over a
|
|
Packit |
3c2767 |
socket connection is not supported. It is easy to support (we just
|
|
Packit |
3c2767 |
need a variation of @code{assuan_socket_connect} which takes an
|
|
Packit |
3c2767 |
already connected socket FD and turns it into an Assuan context), so
|
|
Packit |
3c2767 |
if you need this let us know.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
After connecting, get the inbound status FD with
|
|
Packit |
3c2767 |
@code{assuan_get_active_fds} (the first one returned is the status
|
|
Packit |
3c2767 |
FD). This FD can be duplicated if it is convenient (GPGME does this
|
|
Packit |
3c2767 |
to be able to close this FD and associated callback handlers without
|
|
Packit |
3c2767 |
disrupting Assuan's internals).
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
Then register the Assuan inbound status FD and all bulk data FDs with
|
|
Packit |
3c2767 |
the I/O event mechanism. In general, this requires setting up
|
|
Packit |
3c2767 |
callback handlers for these FDs and registering them with the main
|
|
Packit |
3c2767 |
event loop.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
When bulk data FDs become ready, you can simply perform the
|
|
Packit |
3c2767 |
corresponding read or write operations. When the inbound status FD
|
|
Packit |
3c2767 |
becomes ready, you can receive the next server line with
|
|
Packit |
3c2767 |
assuan_read_line().
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
You should close and unregister the bulk data FDs when you wrote all
|
|
Packit |
3c2767 |
data (for outbound FDs) or receive an EOF (for inbound FDs). When you
|
|
Packit |
3c2767 |
receive an ERR from the server, or an OK for the final operation, you
|
|
Packit |
3c2767 |
can unregister the inbound status FD and call @code{assuan_release}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
As noted above, all send operations on the outbound status FD are done
|
|
Packit |
3c2767 |
immediate with blocking. In GPGME, this has never caused any problems.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
The @code{INQUIRE} function can be handled in two ways: If the
|
|
Packit |
3c2767 |
requested data is immediately available, the client can just send the
|
|
Packit |
3c2767 |
data blockingly. If the requested data needs to be fetched from a
|
|
Packit |
3c2767 |
blocking source, a callback handler can be registered for the FD with
|
|
Packit |
3c2767 |
the main event loop. GPGME does not support the @code{INQUIRE}
|
|
Packit |
3c2767 |
function, so we do not have any practical experience with this.
|
|
Packit |
3c2767 |
@end enumerate
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Currently, the client can not cancel a pending operation gracefully.
|
|
Packit |
3c2767 |
It can, however, disconnect from the server at any time. It is the
|
|
Packit |
3c2767 |
responsibility of the server to periodically send status messages to
|
|
Packit |
3c2767 |
the client to probe if the connection remains alive.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node External I/O Loop Server
|
|
Packit |
3c2767 |
@section External I/O event loops in the server.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Currently, no Assuan server exists which uses external I/O event
|
|
Packit |
3c2767 |
loops. However, the following guidelines should lead to a usable
|
|
Packit |
3c2767 |
implementation:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@enumerate
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
For socket servers: You can not use @code{assuan_accept}, so you
|
|
Packit |
3c2767 |
should just implement the bind/connect/listen/accept stage yourself.
|
|
Packit |
3c2767 |
You can register the listen FD with your main event loop, accept the
|
|
Packit |
3c2767 |
connection when it becomes ready, and finally call
|
|
Packit |
3c2767 |
@code{assuan_init_socket_server} with the final argument being
|
|
Packit |
3c2767 |
@code{ASSUAN_SOCKET_SERVER_ACCEPTED} to create an Assuan context for this
|
|
Packit |
3c2767 |
connection. This way you can also handle multiple connections in
|
|
Packit |
3c2767 |
parallel. The reference implementation for this approach is DirMngr.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
For pipe servers: @code{assuan_init_pipe_server} creates an Assuan
|
|
Packit |
3c2767 |
context valid for the pipe FDs.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
Once you have a context for a single connection, you can get the
|
|
Packit |
3c2767 |
inbound status FD with @code{assuan_get_active_fds} (the first one
|
|
Packit |
3c2767 |
returned is the status FD). This FD can be duplicated if it is
|
|
Packit |
3c2767 |
convenient. Every time the inbound status FD is readable, you should
|
|
Packit |
3c2767 |
invoke the function @code{assuan_process_next} (see below) to process
|
|
Packit |
3c2767 |
the next incoming message. @code{assuan_process_next} processes as
|
|
Packit |
3c2767 |
many status lines as can be received by a single @code{read}
|
|
Packit |
3c2767 |
operation. When it returns, the inbound status FD may still be
|
|
Packit |
3c2767 |
readable, but Assuan does not check this.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The function @code{assuan_process_next} returns 0 if it can not make
|
|
Packit |
3c2767 |
progress reliably, and it returns true in @code{done} if the client
|
|
Packit |
3c2767 |
closed the connection. See below for more information on this
|
|
Packit |
3c2767 |
function.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item
|
|
Packit |
3c2767 |
The command will be dispatched by @code{assuan_process_next} just as
|
|
Packit |
3c2767 |
with @code{assuan_process}, however, you will want to implement the
|
|
Packit |
3c2767 |
command handlers in such a way that they do not block. For example,
|
|
Packit |
3c2767 |
the command handler may just register the bulk data FDs with the main
|
|
Packit |
3c2767 |
event loop and return.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
When the command is finished, irregardless if this happens directly in
|
|
Packit |
3c2767 |
the command handler or later, you must call @code{assuan_process_done}
|
|
Packit |
3c2767 |
with an appropriate error value (or 0 for success) to return an
|
|
Packit |
3c2767 |
appropriate status line to the client. You can do this at the end of
|
|
Packit |
3c2767 |
the command handler, for example by ending it with @code{return
|
|
Packit |
3c2767 |
assuan_process_done (error_code);}. Another possibility is to invoke
|
|
Packit |
3c2767 |
@code{assuan_process_done} from the place in the code which closes the
|
|
Packit |
3c2767 |
last active bulk FD registered with the main event loop for this
|
|
Packit |
3c2767 |
operation.
|
|
Packit |
3c2767 |
@end enumerate
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
It is not possible to use @code{assuan_inquire} in a command handler,
|
|
Packit |
3c2767 |
as this function blocks on receiving the inquired data from the
|
|
Packit |
3c2767 |
client. Instead, the asynchronous version @code{assuan_inquire_ext}
|
|
Packit |
3c2767 |
needs to be used (see below), which invokes a callback when the client
|
|
Packit |
3c2767 |
provided the inquired data. A typical usage would be for the command
|
|
Packit |
3c2767 |
handler to register a continuation with @code{assuan_inquire_ext} and
|
|
Packit |
3c2767 |
return 0. Eventually, the continuation would be invoked by
|
|
Packit |
3c2767 |
@code{assuan_process_next} when the client data arrived. The
|
|
Packit |
3c2767 |
continuation could complete the command and eventually call
|
|
Packit |
3c2767 |
@code{assuan_process_done}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Cancellation is supported by returning an appropriate error value to
|
|
Packit |
3c2767 |
the client with @code{assuan_process_done}. For long running
|
|
Packit |
3c2767 |
operations, the server should send progress status messages to the
|
|
Packit |
3c2767 |
client in regular intervals to notice when the client disconnects.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_process_next (@w{assuan_context_t @var{ctx}}, @w{int *@var{done}})
|
|
Packit |
3c2767 |
This is the same as @code{assuan_process} but the caller has to
|
|
Packit |
3c2767 |
provide the outer loop. He should loop as long as the return code is
|
|
Packit |
3c2767 |
zero and @var{done} is false.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_process_done (@w{assuan_context_t @var{ctx}}, @w{gpg_error_t @var{rc}})
|
|
Packit |
3c2767 |
Finish a pending command and return the error code @var{rc} to the
|
|
Packit |
3c2767 |
client.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_inquire_ext (@w{assuan_context_t @var{ctx}}, @w{const char *@var{keyword}}, @w{size_t @var{maxlen}}, @w{gpg_error_t (*@var{cb}) (void *cb_data, gpg_error_t rc, unsigned char *buffer, size_t buffer_len)}, @w{void *@var{cb_data}})
|
|
Packit |
3c2767 |
This is similar to @code{assuan_inquire} but the caller has to provide
|
|
Packit |
3c2767 |
the outer loop (using @code{assuan_process_next}). The caller should
|
|
Packit |
3c2767 |
specify a continuation with @var{cb}, which receives @var{cb_data} as
|
|
Packit |
3c2767 |
its first argument, and the error value as well as the inquired data as
|
|
Packit |
3c2767 |
its remaining arguments.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@c U T I L I T I E S
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@node Utilities
|
|
Packit |
3c2767 |
@chapter Utility functions
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
There are a lot of helper functions to make writing Assuan code easier.
|
|
Packit |
3c2767 |
Some of these functions provide information not available with the
|
|
Packit |
3c2767 |
general functions.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_write_status (@w{assuan_context_t @var{ctx}}, @w{const char *@var{keyword}}, @w{const char *@var{text}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This is a convenience function for a server to send a status line. You
|
|
Packit |
3c2767 |
need to pass it the @var{keyword} and the content of the status line in
|
|
Packit |
3c2767 |
@var{text}.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_inquire (@w{assuan_context_t @var{ctx}}, @w{const char *@var{keyword}}, @w{unsigned char **@var{r_buffer}}, @w{size_t *@var{r_length}}, @w{size_t @var{maxlen}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
A server may use this function to request specific data from a client.
|
|
Packit |
3c2767 |
This function sends an 'INQUIRE' command back to the client and
|
|
Packit |
3c2767 |
returns the client's response in a newly allocated buffer. You need
|
|
Packit |
3c2767 |
to pass at least the server's context (@var{ctx}) and a description of
|
|
Packit |
3c2767 |
the required data (@var{keyword}). All other parameters may be
|
|
Packit |
3c2767 |
@code{NULL} or @code{0}, but this is rarely useful.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
On success the result is stored in a newly allocated buffer stored at
|
|
Packit |
3c2767 |
@var{r_buffer}. The length of the data is stored at @var{r_length}.
|
|
Packit |
3c2767 |
If @var{maxlen} has not been given as @code{0}, it specifies an upper
|
|
Packit |
3c2767 |
size limit of the expected data. If the client returns too much
|
|
Packit |
3c2767 |
data the function fails and an error with the error code
|
|
Packit |
3c2767 |
@code{GPG_ERR_ASS_TOO_MUCH_DATA} will be returned.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun FILE* assuan_get_data_fp (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Return a stdio stream for the Assuan context @var{ctx}. This stream may
|
|
Packit |
3c2767 |
then be used for data output (assuan_write_data). The stream is valid
|
|
Packit |
3c2767 |
until the end of the current handler. Calling @code{fclose} for that stream is
|
|
Packit |
3c2767 |
not required. Assuan does all the buffering needed to insert the status
|
|
Packit |
3c2767 |
line as well as the required line wrapping and quoting for data lines.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This function is only available on systems supporting either
|
|
Packit |
3c2767 |
@code{funopen} or @code{fopencookie}. If it is not supported @code{NULL}
|
|
Packit |
3c2767 |
is returned and @code{errno} is set to @code{ENOSYS}.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_set_okay_line (@w{assuan_context_t @var{ctx}}, @w{const char *@var{line}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Set the text used for the next @code{OK} response to @var{line}. This is
|
|
Packit |
3c2767 |
sometimes useful to send additional human readable information along
|
|
Packit |
3c2767 |
with the OK line. The string is automatically reset at the end of the
|
|
Packit |
3c2767 |
current handler.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_command_parse_fd (@w{assuan_context_t @var{ctx}}, @w{char *@var{line}}, @w{assuan_fd_t *@var{rfd}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This is the core of the default @code{INPUT} and @code{OUTPUT}
|
|
Packit |
3c2767 |
handler. It may be used in custom commands as well to negotiate a
|
|
Packit |
3c2767 |
file descriptor. If @var{line} contains @code{FD=@var{n}}, it returns
|
|
Packit |
3c2767 |
@var{n} in @var{rfd} assuming a local file descriptor. If @var{line}
|
|
Packit |
3c2767 |
contains just @code{FD} it returns a file descriptor at @var{rfd};
|
|
Packit |
3c2767 |
this file descriptor needs to have been sent by the client right
|
|
Packit |
3c2767 |
before using @code{assuan_sendfd}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
On W32 systems the returned file descriptor is a system handle and not a
|
|
Packit |
3c2767 |
libc low level I/O file descriptor. Thus applications need to use
|
|
Packit |
3c2767 |
@code{_open_osfhandle} before they can pass this descriptor to standard
|
|
Packit |
3c2767 |
functions like @code{fdopen} or @code{dup}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun @w{const char *} assuan_get_command_name (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Return the name of the command currently processed by a handler.
|
|
Packit |
3c2767 |
The returned string is valid until the next call to an Assuan
|
|
Packit |
3c2767 |
function on the same context. Returns @code{NULL} if no handler is
|
|
Packit |
3c2767 |
executed or the command is not known.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun assuan_fd_t assuan_get_input_fd (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Return the file descriptor sent by the client using the last @code{INPUT}
|
|
Packit |
3c2767 |
command. Returns @code{ASSUAN_INVALID_FD} if no file descriptor is available.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun assuan_fd_t assuan_get_output_fd (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Return the file descriptor sent by the client using the last
|
|
Packit |
3c2767 |
@code{OUTPUT} command. Returns @code{ASSUAN_INVALID_FD} if no file descriptor is
|
|
Packit |
3c2767 |
available.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_close_input_fd (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Close the file descriptor set by the last @code{INPUT} command. This
|
|
Packit |
3c2767 |
function has the advantage over a simple @code{close} that it can do
|
|
Packit |
3c2767 |
some sanity checks and make sure that a following
|
|
Packit |
3c2767 |
@code{assuan_get_input_fd} won't return an already closed descriptor.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_close_output_fd (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Close the file descriptor set by the last @code{OUTPUT} command. This
|
|
Packit |
3c2767 |
function has the advantage over a simple @code{close} that it can do
|
|
Packit |
3c2767 |
some sanity checks and make sure that a following
|
|
Packit |
3c2767 |
@code{assuan_get_input_fd} won't return an already closed descriptor.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_set_error (@w{assuan_context_t @var{ctx}}, @w{gpg_error_t @var{err}}, @w{const char *@var{text}})
|
|
Packit |
3c2767 |
This is a helper to provide a more descriptive error text with @code{ERR}
|
|
Packit |
3c2767 |
lines. For this to work, the text needs to be stored in the context
|
|
Packit |
3c2767 |
@var{ctx} while still being in the command handler. This function is
|
|
Packit |
3c2767 |
commonly called this way
|
|
Packit |
3c2767 |
@smallexample
|
|
Packit |
3c2767 |
return assuan_set_error (ctx, err, "commands needs 5 arguments");
|
|
Packit |
3c2767 |
@end smallexample
|
|
Packit |
3c2767 |
The value @var{err} is passed through and thus the return value of the
|
|
Packit |
3c2767 |
command handler in the example. The provided text further explains
|
|
Packit |
3c2767 |
that error to humans.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun pid_t assuan_get_pid (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This function returns the pid of the connected connected peer. If
|
|
Packit |
3c2767 |
that pid is not known @code{ASSUAN_INVALID_PID} is returned. Note
|
|
Packit |
3c2767 |
that it is not always possible to learn the pid of the other
|
|
Packit |
3c2767 |
process. For a pipe based server the client knows it instantly and a
|
|
Packit |
3c2767 |
mechanism is in place to let the server learn it. For socket based
|
|
Packit |
3c2767 |
servers the pid is only available on systems providing the
|
|
Packit |
3c2767 |
@code{SO_PEERCRED} socket option @footnote{to our knowledge only the
|
|
Packit |
3c2767 |
Linux kernel has this feature}.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftp {Data type} {assuan_peercred_t}
|
|
Packit |
3c2767 |
This structure is used to store the peer credentials. The available
|
|
Packit |
3c2767 |
members depend on the operating system.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item pid_t pid
|
|
Packit |
3c2767 |
The process ID of the peer.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item uid_t uid
|
|
Packit |
3c2767 |
The user ID of the peer process.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item gid_t gid
|
|
Packit |
3c2767 |
The group ID of the peer process.
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
@end deftp
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_get_peercred (@w{assuan_context_t @var{ctx}}, @w{assuan_peercred_t *@var{peercred}})
|
|
Packit |
3c2767 |
Return user credentials of the peer. This will work only on certain
|
|
Packit |
3c2767 |
systems and only when connected over a socket. On success, a pointer
|
|
Packit |
3c2767 |
to the peer credentials is stored in @var{peercred}. The information
|
|
Packit |
3c2767 |
is only valid as long as the state of the connection is unchanged (at
|
|
Packit |
3c2767 |
least until the next assuan call to the same context).
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
As of now only the server is able to retrieve this information. Note,
|
|
Packit |
3c2767 |
that for getting the pid of the peer @code{assuan_get_pid} is usually
|
|
Packit |
3c2767 |
better suited.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun int assuan_get_active_fds (@w{assuan_context_t @var{ctx}}, @w{int @var{what}}, @w{assuan_fd_t *@var{fdarray}}, @w{int @var{fdarraysize}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Return all active file descriptors for the context @var{ctx}. This
|
|
Packit |
3c2767 |
function can be used to select on the file descriptors and to call
|
|
Packit |
3c2767 |
@code{assuan_process_next} if there is an active one. The first
|
|
Packit |
3c2767 |
descriptor in the array is the one used for the command connection.
|
|
Packit |
3c2767 |
Currently @var{what} needs to be @code{0} to return descriptors used for
|
|
Packit |
3c2767 |
reading, @code{1} will eventually be used to return descriptors used for
|
|
Packit |
3c2767 |
writing. @var{fdarray} is an array of integers provided by the caller;
|
|
Packit |
3c2767 |
@var{fdarraysize} gives the size of that array.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
On success the number of active descriptors are returned. These active
|
|
Packit |
3c2767 |
descriptors are then stored in @var{fdarray}. On error @code{-1} is
|
|
Packit |
3c2767 |
returned; the most likely reason for this is a too small @var{fdarray}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Note that on W32 systems the returned file descriptor is a system handle
|
|
Packit |
3c2767 |
and not a libc low level I/O file descriptor.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun int assuan_pending_line (@w{assuan_context_t @var{ctx}})
|
|
Packit |
3c2767 |
A call to this function return true if a full line has been buffered and
|
|
Packit |
3c2767 |
thus an entire assuan line may be read without triggering any actual
|
|
Packit |
3c2767 |
I/O.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@c S O C K E T W R A P P E R S
|
|
Packit |
3c2767 |
@c
|
|
Packit |
3c2767 |
@node Socket wrappers
|
|
Packit |
3c2767 |
@chapter Socket wrapper functions
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@noindent
|
|
Packit |
3c2767 |
It is sometimes useful to support Unix domain sockets on Windows. To do
|
|
Packit |
3c2767 |
this in a portable way, Assuan provides a set of wrapper functions which
|
|
Packit |
3c2767 |
may be used on any system but will enhance Windows to support these
|
|
Packit |
3c2767 |
socket types. The actual implementation is based on local TCP sockets
|
|
Packit |
3c2767 |
and fully transparent for the client. Server code needs to utilize two
|
|
Packit |
3c2767 |
extra functions to check the permissions.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_sock_init (void)
|
|
Packit |
3c2767 |
Initialize the socket wrappers. Must be called once at startup if any
|
|
Packit |
3c2767 |
of the socket wrapper functions are used.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun gpg_error_t assuan_sock_deinit (void)
|
|
Packit |
3c2767 |
Deinitialize the socket wrappers.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun int assuan_sock_close (@w{assuan_fd_t @var{fd}})
|
|
Packit |
3c2767 |
Wrapper for close which does a closesocket on Windows if needed.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun assuan_fd_t assuan_sock_new (@w{int @var{domain}}, @w{int @var{type}}, @w{int @var{proto}});
|
|
Packit |
3c2767 |
Wrapper around socket.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun int assuan_sock_connect (@w{assuan_fd_t @var{sockfd}}, @
|
|
Packit |
3c2767 |
@w{struct sockaddr *@var{addr}}, @
|
|
Packit |
3c2767 |
@w{int @var{addrlen}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Wrapper around connect. For Unix domain sockets under Windows this
|
|
Packit |
3c2767 |
function also does a write immediately after the the connect to send the
|
|
Packit |
3c2767 |
nonce as read from the socket's file. Under Unix this function check
|
|
Packit |
3c2767 |
whether the socket file is a redirection file and connects to the
|
|
Packit |
3c2767 |
redirected socket instead; see @code{assuan_sock_set_sockaddr_un} for
|
|
Packit |
3c2767 |
details on the redirection file format.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun int assuan_sock_connect_byname (@w{const char * @var{host}}, @
|
|
Packit |
3c2767 |
@w{unsigned short @var{port}}, @
|
|
Packit |
3c2767 |
@w{int @var{reserved}}, @
|
|
Packit |
3c2767 |
@w{const char *@var{credentials}}, @
|
|
Packit |
3c2767 |
@w{unsigned int @var{flags}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Directly connect to @var{port} on @var{host} given as a name. The
|
|
Packit |
3c2767 |
current implementation requires that @var{flags} has either
|
|
Packit |
3c2767 |
@code{ASSUAN_SOCK_SOCKS} or @code{ASSUAN_SOCK_TOR} set. On success a
|
|
Packit |
3c2767 |
new TCP STREAM socket is returned; on error @code{ASSUAN_INVALID_FD}
|
|
Packit |
3c2767 |
and ERRNO set. If @var{credentials} is not @code{NULL}, it is a
|
|
Packit |
3c2767 |
string used for password based SOCKS authentication. Username and
|
|
Packit |
3c2767 |
password are separated by a colon. @var{reserved} should be 0. To
|
|
Packit |
3c2767 |
test whether the proxy is available @var{host} and @var{port} may be
|
|
Packit |
3c2767 |
given as NULL/0: If the proxy is available the function returns a
|
|
Packit |
3c2767 |
valid socket which is in the state after credentials sub-negotiation.
|
|
Packit |
3c2767 |
The caller now knows that the SOCKS proxy is available and has been
|
|
Packit |
3c2767 |
authenticated; normally the caller closes the socket then.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun int assuan_sock_bind ( @
|
|
Packit |
3c2767 |
@w{assuan_fd_t @var{sockfd}}, @
|
|
Packit |
3c2767 |
@w{struct sockaddr *@var{addr}}, @
|
|
Packit |
3c2767 |
@w{int @var{addrlen}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Wrapper around bind. Under Windows this creates a file and writes the
|
|
Packit |
3c2767 |
port number and a random nonce to this file.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun int assuan_sock_set_sockaddr_un ( @
|
|
Packit |
3c2767 |
@w{const char *@var{fname}}, @
|
|
Packit |
3c2767 |
@w{struct sockaddr *@var{addr}}, @
|
|
Packit |
3c2767 |
@w{int *@var{r_redirected}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This is a helper function to initialize the Unix socket domain address
|
|
Packit |
3c2767 |
structure @var{addr} and store the file name @var{fname} there. If
|
|
Packit |
3c2767 |
@var{r_redirected} is not NULL the function checks whether @var{fname}
|
|
Packit |
3c2767 |
already exists, is a regular file, and not a socket. In that case
|
|
Packit |
3c2767 |
@var{fname} is read to see whether this is a redirection to a socket
|
|
Packit |
3c2767 |
file. If that is the case 1 is stored at @var{r_redirected}. If the
|
|
Packit |
3c2767 |
file does not look like a redirection file 0 will be stored there and
|
|
Packit |
3c2767 |
@var{fname} will be used in the regular way.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The format of a redirection file is
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@example
|
|
Packit |
3c2767 |
%Assuan%
|
|
Packit |
3c2767 |
socket=@var{name}
|
|
Packit |
3c2767 |
@end example
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
With @var{name} being is the actual socket to use. No white spaces
|
|
Packit |
3c2767 |
are allowed, both lines must be terminated by a single linefeed, and
|
|
Packit |
3c2767 |
extra lines are not allowed. Environment variables are interpreted in
|
|
Packit |
3c2767 |
@var{name} if given in @code{$@{VAR@}} notation. No escape characters
|
|
Packit |
3c2767 |
are defined; if the string @code{$@{} shall be used in file name, an
|
|
Packit |
3c2767 |
environment variable with that content may be used. The length of the
|
|
Packit |
3c2767 |
redirection file is limited to 511 bytes which is more than sufficient
|
|
Packit |
3c2767 |
for any known implementation of Unix domain sockets.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun int assuan_sock_get_nonce ( @
|
|
Packit |
3c2767 |
@w{struct sockaddr *@var{addr}}, @
|
|
Packit |
3c2767 |
@w{int @var{addrlen}}, @
|
|
Packit |
3c2767 |
@w{assuan_sock_nonce_t *@var{nonce}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
This is used by the server after a bind to return the random nonce. To
|
|
Packit |
3c2767 |
keep the code readable this may also be used on POSIX system.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun int assuan_sock_check_nonce ( @
|
|
Packit |
3c2767 |
@w{assuan_fd_t @var{fd}}, @
|
|
Packit |
3c2767 |
@w{assuan_sock_nonce_t *@var{nonce}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
If the option @code{ASSUAN_SOCKET_SERVER_ACCEPTED} has been used,
|
|
Packit |
3c2767 |
Libassuan has no way to check the nonce of the server. Thus an explicit
|
|
Packit |
3c2767 |
check of the saved nonce using this function is required. If this
|
|
Packit |
3c2767 |
function fails the server should immediately drop the connection. This
|
|
Packit |
3c2767 |
function may not be used if Libassuan does the accept call itself
|
|
Packit |
3c2767 |
(i.e. @code{ASSUAN_SOCKET_SERVER_ACCEPTED} has not been used) because
|
|
Packit |
3c2767 |
in this case Libassuan calls this function internally. See also
|
|
Packit |
3c2767 |
@code{assuan_set_sock_nonce}.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Actually this mechanism is only required on Windows but for cleanness of
|
|
Packit |
3c2767 |
code it may be used on POSIX systems as well, where this function is
|
|
Packit |
3c2767 |
a nop.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
To control certain properties of the wrapper two additional functions
|
|
Packit |
3c2767 |
are provided:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun int assuan_sock_set_flag ( @
|
|
Packit |
3c2767 |
@w{assuan_fd_t @var{fd}}, @
|
|
Packit |
3c2767 |
@w{const char *@var{name}}, @
|
|
Packit |
3c2767 |
@w{int @var{value}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Set the flags @var{name} for socket @var{fd} to @var{value}. See
|
|
Packit |
3c2767 |
below for a list of valid names. Returns 0 on success; on failure
|
|
Packit |
3c2767 |
sets ERRNO and returns -1.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@deftypefun int assuan_sock_get_flag ( @
|
|
Packit |
3c2767 |
@w{assuan_fd_t @var{fd}}, @
|
|
Packit |
3c2767 |
@w{const char *@var{name}}, @
|
|
Packit |
3c2767 |
@w{int *@var{r_value}})
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Store the current value of the flag @var{name} for socket @var{fd} at
|
|
Packit |
3c2767 |
@var{r_value}. See below for a list of valid names. Returns 0 on
|
|
Packit |
3c2767 |
success; on failure sets ERRNO and returns -1.
|
|
Packit |
3c2767 |
@end deftypefun
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
The supported flags are:
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@table @code
|
|
Packit |
3c2767 |
@item cygwin
|
|
Packit |
3c2767 |
This flag has an effect only on Windows. If the value is 1, the
|
|
Packit |
3c2767 |
socket is set into Cygwin mode so that Cygwin clients can connect to
|
|
Packit |
3c2767 |
such a socket. This flag needs to be set before a bind and should not
|
|
Packit |
3c2767 |
be changed during the lifetime of the socket. There is no need to set
|
|
Packit |
3c2767 |
this flag for connecting to a Cygwin style socket because no state is
|
|
Packit |
3c2767 |
required at the client. On non-Windows platforms setting this flag is
|
|
Packit |
3c2767 |
ignored, reading the flag always returns a value of 0.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@item tor-mode
|
|
Packit |
3c2767 |
@itemx socks
|
|
Packit |
3c2767 |
If @var{value} is 1 globally enable SOCKS5 mode for new connections
|
|
Packit |
3c2767 |
using IPv6 or IPv4. @var{fd} must be set to @code{ASSUAN_INVALID_FD} A
|
|
Packit |
3c2767 |
future extension may allow to disable SOCKS5 mode for a specified
|
|
Packit |
3c2767 |
socket but globally disabling SOCKS5 mode is not possible. Using the
|
|
Packit |
3c2767 |
flag ``tor-mode'' expects the SOCKS5 proxy to listen on port 9050, the
|
|
Packit |
3c2767 |
flag ``socks'' expects the proxy to listen on port 1080.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
Connections to the loopback address are not routed though the SOCKS
|
|
Packit |
3c2767 |
proxy. UDP requests are not supported at all. The proxy will be
|
|
Packit |
3c2767 |
connected at address 127.0.0.1; an IPv6 connection to the proxy is not
|
|
Packit |
3c2767 |
yet supported.
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@end table
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c ---------------------------------------------------------------------
|
|
Packit |
3c2767 |
@c Legal BS
|
|
Packit |
3c2767 |
@c ---------------------------------------------------------------------
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@include lgpl.texi
|
|
Packit |
3c2767 |
@include gpl.texi
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c ---------------------------------------------------------------------
|
|
Packit |
3c2767 |
@c Indexes
|
|
Packit |
3c2767 |
@c ---------------------------------------------------------------------
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@node Index
|
|
Packit |
3c2767 |
@unnumbered Index
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@printindex cp
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@c ---------------------------------------------------------------------
|
|
Packit |
3c2767 |
@c Epilogue
|
|
Packit |
3c2767 |
@c ---------------------------------------------------------------------
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
@bye
|
|
Packit |
3c2767 |
|
|
Packit |
3c2767 |
|