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