[Pkg-gnupg-commit] [libassuan] 428/437: Documentation cleanups.
Eric Dorland
eric at moszumanska.debian.org
Fri May 22 05:34:13 UTC 2015
This is an automated email from the git hooks/post-receive script.
eric pushed a commit to branch master
in repository libassuan.
commit ccd1811479e9d30dcd207a5031eda07958459fe2
Author: Neal H. Walfield <neal at gnu.org>
Date: Thu May 7 14:51:04 2015 +0200
Documentation cleanups.
---
doc/assuan.texi | 238 ++++++++++++++++++++++++++++++++------------------------
1 file changed, 136 insertions(+), 102 deletions(-)
diff --git a/doc/assuan.texi b/doc/assuan.texi
index b932be0..78d3658 100644
--- a/doc/assuan.texi
+++ b/doc/assuan.texi
@@ -140,29 +140,34 @@ Indices
@node Introduction
@chapter Introduction to Assuan
-In an ideal world, Assuan would not be necessary. Assuan's primary
-use is to allow a client to interact with a non-persistent server.
-Using Assuan, this is accomplished by forking a subprocess and
-communicating with it via, for example, a pipe or Unix domain socket.
-This method is neither elegant nor efficient, especially when there is
-a lot of data spread across several transactions: not only is there a
-penalty for an increased number of context switches, but also a
-significant amount of data is @var{memcpy}ed from the client to a file
-descriptor and from the file descriptor to the server. Despite these
-and other disadvantages, this type of client/server communication can
-be useful: the client is completely separate from the server; they are
-in different address spaces. This is especially important in
-situations where the server must have a known degree of reliability
-and data must be protected: as the Assuan protocol is well defined and
-clients cannot corrupt the servers' address space, auditing becomes
-much easier.
-
-Assuan was developed for use by the GNU Privacy Guard, GnuPG, to
+Assuan is an extensible inter-process communication (IPC) protocol and
+library. It is designed for point-to-point communication and it
+doesn't provide a naming system. To contact a server, either the
+client must know how to locate the server, e.g., via a well-known Unix
+domain socket, or, if the server is transient, how to start it. In
+the latter case, Assuan provides functionality to start the server
+process.
+
+In Assuan, communication is typically either via a pipe or a Unix
+domain socket. This method is neither elegant nor efficient,
+especially when there is a lot of data spread across several
+transactions. Not only is there a penalty for an increased number of
+context switches, but a significant amount of data is @var{memcpy}ed
+from the client to a file descriptor and from the file descriptor to
+the server. Despite these and other disadvantages, this type of
+client/server communication is useful: the client is separated from
+the server: they run in different address spaces. This is especially
+important in situations where the server must have a known degree of
+reliability and data must be protected: as the Assuan protocol is well
+defined and clients cannot corrupt the servers' address space,
+auditing becomes much easier.
+
+Assuan was developed for use by the GNU Privacy Guard (GnuPG) to
prevent potentially buggy clients from unwittingly corrupting
sensitive transactions or compromising data such as a secret key.
-Assuan permits the servers, which do the actual work, e.g. encryption
+Assuan permits the servers, which do the actual work, e.g., encryption
and decryption of data using a secret key, to be developed
-independently of the user interfaces, e.g. mail clients and other
+independently of the user interfaces, e.g., mail clients and other
encryption front ends. Like a shared library, the interface is well
defined and any number of front ends can use it; however, unlike a
shared library, the client cannot see or touch the server's data. As
@@ -171,15 +176,15 @@ understandable and less error prone.
Assuan is not, however, limited to use with GnuPG servers and clients:
it was designed to be flexible enough to meet the demands of many
-transaction based environments with non-persistent servers.
+transaction-based environments.
@node Assuan
@chapter Description of the Assuan protocol.
The architecture of the modular GnuPG system is based on several
-highly specialized modules which compose a network of client/server
-communication. A common framework for intermodule communication is
-therefore needed and should be implemented in a library.
+highly specialized modules which form a network of clients and
+servers. A common framework for intermodule communication is
+therefore needed and implemented as a library.
Goals:
@@ -214,18 +219,18 @@ Design criteria:
The implementation is line based with a maximum line size of 1000
octets. The default IPC mechanism is Unix Domain Sockets.
-On a connect request the server responds either with an okay or an
-error status. For authentication-check the server may send an Inquiry
-response prior to the first Okay, and it may also issue Status
-messages. The server must check that the client is allowed to
-connect, this is done by requesting the credentials for the peer and
-comparing them to those of the server. This avoids attacks based on
-wrong socket permissions.
+On connect, the server responds either with okay or an error status.
+To perform an authentication check, the server may send an Inquiry
+response prior to the first Okay. It may also issue Status messages.
+The server must check that the client is allowed to connect. This is
+done by requesting the credentials for the peer and comparing them
+with the server's credentials. This avoids attacks based on wrong
+socket permissions.
-It may choose to delay the first response in case of an error. The
-server never closes the connection - however the lower protocol may do
-so after some time of inactivity or when the connection is in an error
-state.
+The server may choose to delay the first response in case of an error.
+The server, however, never closes the connection, however, the lower
+protocol may do so after some time of inactivity or when the
+connection enters an error state.
All textual messages are assumed to be in UTF-8 unless otherwise noted.
@@ -249,42 +254,70 @@ Request could not be fulfilled. The possible error codes are defined
by @code{libgpg-error}.
@item S @var{keyword} <status information depending on keyword>
-Informational output by the server, still processing the request. A
-client may not send such lines to the server while processing an Inquiry
-command. @var{keyword} shall start with a letter or an underscore.
+Informational output by the server, which is still processing the
+request. A client may not send such lines to the server while
+processing an Inquiry command. @var{keyword} shall start with a
+letter or an underscore.
@item # <string>
Comment line issued only for debugging purposes. Totally ignored.
@item D <raw data>
Raw data returned to client. There must be exactly one space after the
-'D'. The values for '%', CR and LF must be percent escaped; this is
-encoded as %25, %0D and %0A. Only uppercase letters should be used in
-the hexadecimal representation. Other characters may be percent escaped
-for easier debugging. All these Data lines are considered one data
-stream up to the OK or ERR response. Status and Inquiry Responses
-may be mixed with the Data lines.
+'D'. The values for '%', CR and LF must be percent escaped; these are
+encoded as %25, %0D and %0A, respectively. Only uppercase letters
+should be used in the hexadecimal representation. Other characters
+may be percent escaped for easier debugging. All Data lines are
+considered one data stream up to the OK or ERR response. Status and
+Inquiry Responses may be mixed with the Data lines.
@item INQUIRE @var{keyword} <parameters>
-Server needs further information from the client. The client should
-answer with a command which is allowed after an inquiry. Note that the
-server does not confirm that client command but either continues
-processing or ends processing with an error status. Not all commands
-are allowed.
+The server needs further information from the client. The client
+should respond with data (using the ``D'' command and terminated by
+``END''). Alternatively, the client may cancel the current operation
+by responding with ``CAN''.
@end table
+Consider the following examples (lines prefixed with S indicate text
+that the server sends; lines prefixed with C indicate text that the
+client sends):
+
+ at example
+S: INQUIRE foo
+C: D foo bar
+C: D bar baz
+C: END
+[Server continues normal work]
+ at end example
+
+This implements a callback to the client:
+
+ at example
+S: INQUIRE foo
+C: END
+[Server continues]
+ at end example
+
+and:
+
+ at example
+S: INQUIRE foo
+C: CAN
+[Server terminates the operaion and in most cases returns an ERR to the client.]
+ at end example
+
+But, CAN may also mean ``I have no data for you, try to get it from
+elsewhere.''
-A client should only check the first letter of each line and then skip
-over to the next token (except for data lines where the raw data starts
-exactly after 2 bytes). Lines larger than 1000 bytes should be
-treated as a communication error. (The rationale for having a line
-length limit is to allow for easier multiplexing of several channels).
+Note: lines longer than 1000 bytes should be treated as a
+communication error. (The rationale for having a line length limit is
+to allow for easier multiplexing of several channels.)
@node Client requests
@section Client requests
-The server waits for client requests after he sent an Okay or Error.
+The server waits for client requests after sending an Okay or Error.
The client should not issue a request in other cases.
@example
@@ -292,30 +325,31 @@ The client should not issue a request in other cases.
@end example
@var{command} is a one word string without preceding white space.
-Parameters are command specific, CR, LF and the percent signs should be
-percent escaped as described above. To send a backslash as the last
-character it should also be percent escaped. Percent escaping is
+Parameters are command specific, CR, LF and the percent signs should
+be percent escaped as described above. To send a backslash as the
+last character it should also be percent escaped. Percent escaping is
allowed anywhere in the parameters but not in the command. The line
-ends with a CR, LF or just a LF.
+ends with a CR, LF pair or just a LF.
Not yet implemented feature: If there is a need for a parameter list
-longer than the line length limit (1000 characters including command and
-CR, LF), the last character of the line (right before the CR/LF or LF)
-must be a non-escape encoded backslash. The following line is then
-expected to be a continuation of the line with the backslash replaced by
-a blank and the line ending removed.
+longer than the line length limit (1000 characters including command
+and CR, LF), the last character of the line (right before the CR/LF or
+LF) must be a unescaped (i.e., literal) backslash. The following line
+is then expected to be a continuation of the line with the backslash
+replaced by a blank and the line ending removed.
@example
D <raw data>
@end example
-Raw data to the server. There must be exactly one space after the 'D'.
-The values for '%', CR and LF must be percent escaped; this is encoded
-as %25, %0D and %0A. Only uppercase letters should be used in the
-hexadecimal representation. Other characters may be percent escaped
-for easier debugging. All these Data lines are considered one data
-stream up to the @code{OK} or @code{ERR} response. Status and Inquiry
-Responses may be mixed with the Data lines.
+Sends raw data to the server. There must be exactly one space after
+the 'D'. The values for '%', CR and LF must be percent escaped.
+These are encoded as %25, %0D and %0A, respectively. Only uppercase
+letters should be used in the hexadecimal representation. Other
+characters may be percent escaped for easier debugging. All Data
+lines are considered one data stream up to the @code{OK} or @code{ERR}
+response. Status and Inquiry Responses may be mixed with the Data
+lines.
@example
END
@@ -324,12 +358,12 @@ END
Lines beginning with a @code{#} or empty lines are ignored. This is
useful to comment test scripts.
-Although the commands are application specific, some of them are used by
-all protocols and partly directly supported by the Assuan library:
+Although the commands are application specific, some of them are used
+by all protocols and partly supported by the Assuan library:
@table @code
@item BYE
-Close the connection. The server will reply with @code{OK}.
+Close the connection. The server will respond with @code{OK}.
@item RESET
Reset the connection but not any existing authentication. The server
@@ -373,7 +407,7 @@ No operation. Returns OK without any action.
@section Error codes
Libassuan is used with gpg-error style error codes. It is recommended
-to set the error source to a different value than the default
+to set the error source to a different value from the default
@code{GPG_ERR_SOURCE_UNKNOWN} by calling @ref{function
assuan_set_gpg_err_source} early.
@@ -384,7 +418,7 @@ assuan_set_gpg_err_source} early.
@node Preparation
@chapter Preparation
-To use @sc{Assuan}, you have to perform some changes to your
+To use @sc{Assuan}, you have to make some changes to your
sources and the build system. The necessary changes are small and
explained in the following sections.
@@ -408,14 +442,14 @@ file, like this:
#include <assuan.h>
@end example
-The name space of @code{libassuan} is @code{assuan_*} for function
+The namespace of @code{libassuan} is @code{assuan_*} for function
and type names and @code{ASSUAN*} for other symbols. In addition the
same name prefixes with one prepended underscore are reserved for
internal use and should never be used by an application.
Because @code{libassuan} makes use of the GPG Error library, using
- at code{libassuan} will also use the @code{GPG_ERR_*} name space
-directly, and the @code{gpg_err*} and @code{gpg_str*} name space
+ at code{libassuan} will also use the @code{GPG_ERR_*} namespace
+directly, and the @code{gpg_err*} and @code{gpg_str*} namespaces
indirectly.
@@ -459,8 +493,8 @@ link @file{foo.o} with the @code{libassuan} library to a program
gcc -o foo foo.o $(libassuan-config --libs)
@end example
-Of course you can also combine both examples to a single command by
-specifying both options to @command{libassuan-config}:
+You can also combine both examples to a single command by specifying
+both options to @command{libassuan-config}:
@example
gcc -o foo foo.c $(libassuan-config --cflags --libs)
@@ -538,8 +572,8 @@ across contexts.
@node Data Types
@section Data Types used by the library
- at sc{Assuan} uses a context to keep the state for a connection. The
-following data type is used for that:
+ at sc{Assuan} uses a so-called context to store a connection's state.
+The following data type is used for that:
@deftp {Data type} assuan_context_t
The @code{assuan_context_t} type is a pointer to an object maintained
@@ -1257,7 +1291,7 @@ command_handler (int fd)
@end example
@noindent
-This is the first part of the command handler. We start of by
+This is the first part of the command handler. We start off by
allocating a new Assuan context with @code{assuan_new}.
@xref{function assuan_new}.
@@ -1268,30 +1302,30 @@ initialization is thus done using the function:
@deftypefun gpg_error_t assuan_init_pipe_server (@w{assuan_context_t @var{ctx}}, @w{assuan_fd_t @var{filedes}[2]})
-The function takes the two file descriptors from @var{filedes} and
+This function takes the two file descriptors from @var{filedes} and
returns a new Assuan context at @var{r_ctx}. As usual, a return value
-of @code{0} indicates success and a failure is indicated by a
+of @code{0} indicates success and a failure is indicated by
returning an error value. In case of error, @code{NULL} will be stored
at @var{r_ctx}.
In case the server has been called using a bi-directional pipe
(socketpair), @var{filedes} is ignored and the file descriptor is
taken from the environment variable @env{_assuan_connection_fd}. You
-won't need to know that because @code{assuan_pipe_connect}, used
-by the client to connect to such a server, automagically sets this
-variable.
+generally don't need to know this, because @code{assuan_pipe_connect},
+which is called by the client to connect to such a server,
+automagically sets this variable.
@end deftypefun
@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}})
-The function takes the file descriptor @var{fd} which is expected to
-be associated with a socket and an Assuan context @var{ctx}. The
+This function takes the file descriptor @var{fd}, which is expected to
+be associated with a socket, and an Assuan context @var{ctx}. The
following bits are currently defined for @var{flags}:
@table @code
@item ASSUAN_SOCKET_SERVER_FDPASSING
If set, @code{sendmsg} and @code{recvmesg} are used for input and
-output and thus enabling the use of descriptor passing.
+output, which enables the use of descriptor passing.
@item ASSUAN_SOCKET_SERVER_ACCEPTED
If set, @var{fd} refers to an already accepted socket. That is,
Libassuan won't call @var{accept} for it. It is suggested to set this
@@ -1299,7 +1333,7 @@ bit as it allows better control of the connection state.
@end table
As usual, a return value of @code{0} indicates success and a failure
-is indicated by a returning an error value.
+is indicated by returning an error value.
@end deftypefun
@noindent
@@ -1312,8 +1346,8 @@ On the Windows platform the following function needs to be called after
Save a copy of @var{nonce} in context @var{ctx}. This should be used
to register the server's nonce with a context established by
- at code{assuan_init_socket_server}. It is actually only needed for
-Windows but it does not harm to use it on other systems as well.
+ at code{assuan_init_socket_server}. It is technically only needed for
+Windows, but it does no harm to use it on other systems.
@end deftypefun
@@ -1500,18 +1534,18 @@ also allowed to modify that line which makes parsing much easier.
@chapter How to use external I/O event loops
The above implementations of an Assuan client and server are
-synchronous, insofar the main routines block until a request or client
-connection is completely processed. In some programs, for example GUI
-applications, this is undesirable. Instead, Assuan operations should
-be non-blocking, and the caller should be able to poll all involved
-file descriptors to determine when the next Assuan function can be
-invoked without blocking.
+synchronous, insofar as the main routines block until a request or
+client connection is completely processed. In some programs, for
+example GUI applications, this is undesirable. Instead, Assuan
+operations should be non-blocking, and the caller should be able to
+poll all involved file descriptors to determine when the next Assuan
+function can be invoked without blocking.
To make this possible, client and server have to adhere to some rules:
@itemize @bullet
@item
Either partner should always write full lines. If partial lines are
-written, the remainder of the line should b sent without delay.
+written, the remainder of the line should be sent without delay.
@item
Either partner should eagerly receive status messages. While
receiving and sending bulk data may be delayed, the status
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/libassuan.git
More information about the Pkg-gnupg-commit
mailing list