diff options
author | Werner Koch <wk@gnupg.org> | 2003-01-09 14:24:01 +0100 |
---|---|---|
committer | Werner Koch <wk@gnupg.org> | 2003-01-09 14:24:01 +0100 |
commit | e9177199289d39863e29526cb4986ec4a7d9bba8 (patch) | |
tree | 5bf169aae63dd2649de0027708e9f35c02ab43ef /doc/assuan.texi | |
parent | Updated from latest NewPG project (diff) | |
download | gnupg2-e9177199289d39863e29526cb4986ec4a7d9bba8.tar.xz gnupg2-e9177199289d39863e29526cb4986ec4a7d9bba8.zip |
Taken from NewPG
Diffstat (limited to 'doc/assuan.texi')
-rw-r--r-- | doc/assuan.texi | 189 |
1 files changed, 189 insertions, 0 deletions
diff --git a/doc/assuan.texi b/doc/assuan.texi new file mode 100644 index 000000000..fbf513ad8 --- /dev/null +++ b/doc/assuan.texi @@ -0,0 +1,189 @@ +@c Copyright (C) 2002 Free Software Foundation, Inc. +@c This is part of the GnuPG manual. +@c For copying conditions, see the file gnupg.texi. + +@node Assuan +@chapter Description of the Assuan protocol. + +The architecture of the modula GnuPG system is based on a couple of +highly specialized modules which make up a network of client server +communication. A common framework for intermodule communication is +therefore needed and should be implemented in a library. + +Goals: + +@itemize @bullet +@item Common framework for module communication +@item Easy debugging +@item Easy module testing +@item Extendible +@item Optional authentication and encryption facility +@item Usable to access external hardware +@end itemize + + +Design criteria: + +@itemize @bullet +@item Client Server with back channel +@item Use a mainly text based protocol +@item Escape certain control characters +@item Allow indefinite data length +@item Request confidentiality for parts of the communication +@item Dummy module should allow direct linking of client and server. +@item Inline data or descriptor passing for bulk data +@item No protection against DoS needed +@item Subliminal channels are not an issue +@end itemize + +Implementation: + +The implementation is line based with a maximum line size of 1000 +octects. The default IPC mechanism are 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, 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. + +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. + +All textual messages are assumed to be in UTF-8 unless otherwise noted. + + +Server responses: + +@table @code +@item OK [<arbitary debugging information>] +Request was successful. + +@item ERR @var{errorcode} [<human readable error description>] +Request could not be fulfilled. The error codes are mostly application +specific except for a few common ones. + +@item S @var{keyword} <status information depending on keyword> +Informational output by the server, still processing the request. + +@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. + +@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. +@end table + + +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 multiple channels). + + +Client requests: + +The server waits for client requests after he sent an Okay or Error. +The client should not issue a request in other cases with the +exception of the CANCEL command. + +@example +@var{command} <parameters> +@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 +allowed anywhere in the parameters but not in the command. The line +ends with a CR, LF 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. + +@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 OKAY or ERROR response. Status and Inquiry Responses may be +mixed with the Data lines. + +@example +END +@end example + + + +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: + +@table @code +@item CANCEL +his is the one special command which aborts the current request. it can +be sent at any time and the server will stop its operation right before +it would send the next response line (of any type). + +@item BYE +Close the connect, the server will reply with an @code{OK}. + +@item AUTH +Not yet specified as we don't implement it in the first phase. See my +mail to gpa-dev on 2001-10-25 about the rationale for measurements +against local attacks. + +@item RESET +Reset the connection but not any existing authentication. The server +should release all resources associated with the connection. + +@item END +Used by a client to mark the end of raw data. The server may send END +to indicate a partial end of data. +@end table + + +Error Codes: + +Here we keep a list of error codes used in any Assuan based +protocol. The format is the string @code{ERR}, white space, the error +number, white space, a textual description of the error. + +@table @code + +@item 100 Unknown Command +@item 101 Not Implemented + +@item 301 certificate has been revoked [DirMngr] +@item 302 no CRL known for this certificate [DirMngr] +@item 303 CRL is too old and a new one could not be retrieved [DirMngr] + +@end table |