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