1
@c Copyright (C) 2002 Free Software Foundation, Inc.
2
@c This is part of the GnuPG manual.
3
@c For copying conditions, see the file gnupg.texi.
6
@appendix Description of the Assuan protocol.
9
The architecture of the modular GnuPG system is based on a couple of
10
highly specialized modules which make up a network of client server
11
communication. A common framework for intermodule communication is
12
therefore needed and should be implemented in a library.
17
@item Common framework for module communication
19
@item Easy module testing
21
@item Optional authentication and encryption facility
22
@item Usable to access external hardware
26
@appendixsubsec Design criteria
29
@item Client Server with back channel
30
@item Use a mainly text based protocol
31
@item Escape certain control characters
32
@item Allow indefinite data length
33
@item Request confidentiality for parts of the communication
34
@item Dummy module should allow direct linking of client and server.
35
@item Inline data or descriptor passing for bulk data
36
@item No protection against DoS needed
37
@item Subliminal channels are not an issue
41
@appendixsubsec Implementation
44
The implementation is line based with a maximum line size of 1000
45
octects. The default IPC mechanism are Unix Domain Sockets.
47
On a connect request the server responds either with an okay or an error
48
status. For authentication check the server may send an Inquiry
49
Response prior to the first Okay, it may also issue Status messages.
50
The server must check that the client is allowed to connect, this is
51
done by requesting the credentials for the peer and comparing them to
52
those of the server. This avoids attacks based on wrong socket
55
It may choose to delay the first response in case of an error. The
56
server never closes the connection - however the lower protocol may do
57
so after some time of inactivity or when the connection is in an error
60
All textual messages are assumed to be in UTF-8 unless otherwise noted.
63
@appendixsubsec Server responses
66
@item OK [<arbitary debugging information>]
67
Request was successful.
69
@item ERR @var{errorcode} [<human readable error description>]
70
Request could not be fulfilled. The error codes are mostly application
71
specific except for a few common ones.
73
@item S @var{keyword} <status information depending on keyword>
74
Informational output by the server, still processing the request.
77
Comment line issued only for debugging purposes. Totally ignored.
80
Raw data returned to client. There must be exactly one space after the
81
'D'. The values for '%', CR and LF must be percent escaped; this is
82
encoded as %25, %0D and %0A. Only uppercase letters should be used in
83
the hexadecimal representation. Other characters may be percent escaped
84
for easier debugging. All these Data lines are considered one data
85
stream up to the OK or ERR response. Status and Inquiry Responses
86
may be mixed with the Data lines.
88
@item INQUIRE @var{keyword}> <parameters>
89
Server needs further information from the client. The client should
90
answer with a command which is allowed after an inquiry. Note that the
91
server does not confirm that client command but either continues
92
processing or ends processing with an error status. Not all commands
97
A client should only check the first letter of each line and then skip
98
over to the next token (except for data lines where the raw data starts
99
exactly after 2 bytes). Lines larger than 1000 bytes should be
100
treated as a communication error. (The rationale for having a line
101
length limit is to allow for easier multiplexing of multiple channels).
104
@appendixsubsec Client requests
106
The server waits for client requests after he sent an Okay or Error.
107
The client should not issue a request in other cases with the
108
exception of the CANCEL command.
111
@var{command} <parameters>
114
@var{command} is a one word string without preceding white space.
115
Parameters are command specific, CR, LF and the percent signs should be
116
percent escaped as described above. To send a backslash as the last
117
character it should also be percent escaped. Percent escaping is
118
allowed anywhere in the parameters but not in the command. The line
119
ends with a CR, LF or just a LF.
121
Not yet implemented feature: If there is a need for a parameter list
122
longer than the line length limit (1000 characters including command and
123
CR, LF), the last character of the line (right before the CR/LF or LF)
124
must be a non-escape encoded backslash. The following line is then
125
expected to be a continuation of the line with the backslash replaced by
126
a blank and the line ending removed.
132
Raw data to the server. There must be exactly one space after the 'D'.
133
The values for '%', CR and LF must be percent escaped; this is encoded
134
as %25, %0D and %0A. Only uppercase letters should be used in the
135
hexadecimal representation. Other characters may be percent escaped for
136
easier debugging. All these Data lines are considered one data stream
137
up to the OKAY or ERROR response. Status and Inquiry Responses may be
138
mixed with the Data lines.
146
Lines beginning with a @code{#} or empty lines are ignored. This is
147
useful to comment test scripts.
150
Although the commands are application specific, some of them are used by
151
all protocols and partly directly supported by the Assuan library:
155
his is the one special command which aborts the current request. it can
156
be sent at any time and the server will stop its operation right before
157
it would send the next response line (of any type).
160
Close the connect, the server will reply with an @code{OK}.
163
Not yet specified as we don't implement it in the first phase. See my
164
mail to gpa-dev on 2001-10-25 about the rationale for measurements
165
against local attacks.
168
Reset the connection but not any existing authentication. The server
169
should release all resources associated with the connection.
172
Used by a client to mark the end of raw data. The server may send END
173
to indicate a partial end of data.
178
@appendixsubsec Error Codes
180
Here we keep a list of error codes used in any Assuan based
181
protocol. The format is the string @code{ERR}, white space, the error
182
number, white space, a textual description of the error.
186
@item 100 Unknown Command
187
@item 101 Not Implemented
189
@item 301 certificate has been revoked [DirMngr]
190
@item 302 no CRL known for this certificate [DirMngr]
191
@item 303 CRL is too old and a new one could not be retrieved [DirMngr]
added
removed
doc/assuan.texi
