Added missing file
[gnupg.git] / doc / assuan.texi
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.
4
5 @node Assuan
6 @appendix Description of the Assuan protocol.
7 @cindex Assuan, IPC
8
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.
13
14 @appendixsubsec Goals
15
16 @itemize @bullet
17 @item Common framework for module communication
18 @item Easy debugging
19 @item Easy module testing 
20 @item Extendible
21 @item Optional authentication and encryption facility
22 @item Usable to access external hardware
23 @end itemize
24
25
26 @appendixsubsec Design criteria
27
28 @itemize @bullet
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
38 @end itemize
39
40
41 @appendixsubsec Implementation
42
43 @noindent
44 The implementation is line based with a maximum line size of 1000
45 octects.  The default IPC mechanism are Unix Domain Sockets.
46
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
53 permissions.
54
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
58 state.
59
60 All textual messages are assumed to be in UTF-8 unless otherwise noted.
61
62
63 @appendixsubsec Server responses
64
65 @table @code
66 @item OK  [<arbitary debugging information>]
67 Request was successful.
68
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.
72
73 @item S @var{keyword} <status information depending on keyword>
74 Informational output by the server, still processing the request.
75
76 @item # <string>
77 Comment line issued only for debugging purposes.  Totally ignored.
78
79 @item D <raw data>
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.
87
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
93 are allowed.
94 @end table
95
96
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).
102
103
104 @appendixsubsec Client requests
105
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.
109
110 @example
111 @var{command} <parameters>
112 @end example
113
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.
120
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.
127
128 @example
129 D <raw data>
130 @end example
131
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.
139
140 @example
141 END
142 @end example
143
144
145
146 Lines beginning with a @code{#} or empty lines are ignored.  This is
147 useful to comment test scripts.
148
149
150 Although the commands are application specific, some of them are used by
151 all protocols and partly directly supported by the Assuan library:
152
153 @table @code
154 @item CANCEL
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).
158
159 @item BYE
160 Close the connect, the server will reply with an @code{OK}.
161
162 @item AUTH
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.
166
167 @item RESET
168 Reset the connection but not any existing authentication.  The server
169 should release all resources associated with the connection.
170
171 @item END
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.
174 @end table
175
176
177
178 @appendixsubsec Error Codes
179
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.
183
184 @table @code
185
186 @item 100 Unknown Command
187 @item 101 Not Implemented
188
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]
192
193 @end table