Skip to content

Commit e917719

Browse files
dd9jndd9jn
committed
Taken from NewPG
1 parent 3051135 commit e917719

File tree

8 files changed

+2995
-0
lines changed

8 files changed

+2995
-0
lines changed

‎doc/assuan.texi

+189
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
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

‎doc/contrib.texi

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
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 Contributors
6+
@unnumbered Contributors to GnuPG
7+
@cindex contributors
8+
9+
The GnuPG project would like to thank its many contributors. Without
10+
them the project would not have been nearly as successful as it has
11+
been. Any omissions in this list are accidental. Feel free to contact
12+
the maintainer if you have been left out or some of your contributions
13+
are not listed. Please keep this list in alphabetical order.
14+
15+
@itemize @bullet
16+
17+
@item
18+
Bernhard Herzog did extensive testing and tracked down a lot of bugs
19+
20+
@item
21+
Bernhard Reiter made sure that we met the specifications and the
22+
deadlines. He did extensive testing and came up with a lot of suggestions.
23+
24+
@item
25+
Jan-Oliver Wagner made sure that we met the specifications and the
26+
deadlines. He did extensive testing and came up with a lot of suggestions.
27+
28+
@item
29+
Karl-Heinz Zimmer had to struggle with all the bugs and misconceptions
30+
while working on Kmail integration.
31+
32+
@item
33+
Marcus Brinkman cleaned up the Assuan code and fixed bugs all over the place.
34+
35+
@item
36+
Steffen Hansen had a hard time to write the dirmngr due to
37+
underspecified interfaces.
38+
39+
@item
40+
Thomas Koester did extensive testing and tracked down a lot of bugs
41+
42+
@item
43+
Werner Koch desgned the system and wrote most of the original code.
44+
45+
@end itemize
46+
47+
FIXME: We need to copy a lot of credits from GnupG 1.0 to here.
48+
49+
50+
We'd also like to thank the folks who have contributed time and energy in
51+
testing GnuPG:
52+
53+
@itemize @bullet
54+
@item
55+
Joe R. Hacker
56+
57+
@item
58+
And many others
59+
@end itemize
60+
61+
And finally we'd like to thank everyone who uses these tools, submits
62+
bug reports and generally reminds us why we're doing this work in the
63+
first place.

0 commit comments

Comments
 (0)