doc/dbus-sasl-profile.txt

   1 D-BUS Authentication
   2 ===
   3
   4 This document defines a small plain-text protocol used to perform
   5 authentication and negotiate a security layer before the flow of D-BUS
   6 messages begins.  This protocol is intended to be a profile of the
   7 Simple Authentication and Session Layer [SASL].
   8
   9 This document is loosely based on the POP3 SASL profile by John Myers.
  10
  11 Conventions Used in this Document
  12 ===
  13
  14 In examples, "C:" and "S:" indicate lines sent by the client and
  15 server respectively.
  16
  17 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
  18 in this document are to be interpreted as defined in "Key words for
  19 use in RFCs to Indicate Requirement Levels" [RFC 2119]
  20
  21 Protocol Overview
  22 ===
  23
  24 The protocol is a line-based protocol, where each line ends with
  25 \r\n. Each line begins with an all-caps ASCII command name containing
  26 only the character range [A-Z], a space, then any arguments for the
  27 command, then the \r\n ending the line. The protocol is
  28 case-sensitive. All bytes must be in the ASCII character set.
  29
  30 Commands from the client to the server are as follows:
  31
  32    AUTH [mechanism] [initial-response]
  33
  34    CANCEL
  35
  36    BEGIN
  37
  38    DATA <data in base 64 encoding>
  39
  40    ERROR [human-readable error explanation]
  41
  42 From server to client are as follows:
  43
  44    REJECTED <space-separated list of mechanism names>
  45
  46    OK
  47
  48    DATA <data in base 64 encoding>
  49
  50    ERROR
  51
  52 Special credentials-passing nul byte
  53 ===
  54
  55 Immediately after connecting to the server, the client must send a
  56 single nul byte. This byte may be accompanied by credentials
  57 information on some operating systems that use sendmsg() with
  58 SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
  59 sockets. However, the nul byte MUST be sent even on other kinds of
  60 socket, and even on operating systems that do not require a byte to be
  61 sent in order to transmit credentials. The text protocol described in
  62 this document begins after the single nul byte. If the first byte
  63 received from the client is not a nul byte, the server may disconnect
  64 that client.
  65
  66 A nul byte in any context other than the initial byte is an error;
  67 the protocol is ASCII-only.
  68
  69 The credentials sent along with the nul byte may be used with the
  70 SASL mechanism EXTERNAL.
  71
  72 AUTH Command
  73 ===
  74
  75    If an AUTH command has no arguments, it is a request to list
  76    available mechanisms. The server SHOULD respond with a REJECTED
  77    command listing the mechanisms it understands.
  78
  79    If an AUTH command specifies a mechanism, and the server supports
  80    said mechanism, the server SHOULD begin exchanging SASL
  81    challenge-response data with the client using DATA commands.
  82
  83    If the server does not support the mechanism given in the AUTH
  84    command, it SHOULD send a REJECTED command listing the mechanisms
  85    it does support.
  86
  87    If the [initial-response] argument is provided, it is intended for
  88    use with mechanisms that have no initial challenge (or an empty
  89    initial challenge), as if it were the argument to an initial DATA
  90    command. If the selected mechanism has an initial challenge, the
  91    server should reject authentication by sending REJECTED.
  92
  93    If authentication succeeds after exchanging DATA commands,
  94    an OK command should be sent to the client.
  95
  96    The first octet received by the client after the \r\n of the OK
  97    command MUST be the first octet of the authenticated/encrypted
  98    stream of D-BUS messages.
  99
 100    The first octet received by the server after the \r\n of the BEGIN
 101    command from the client MUST be the first octet of the
 102    authenticated/encrypted stream of D-BUS messages.
 103
 104 CANCEL Command
 105 ===
 106
 107    At any time up to sending the BEGIN command, the client may send a
 108    CANCEL command. On receiving the CANCEL command, the server MUST
 109    send a REJECTED command and abort the current authentication
 110    exchange.
 111
 112 DATA Command
 113 ===
 114
 115    The DATA command may come from either client or server, and simply
 116    contains a base64-encoded block of data to be interpreted
 117    according to the SASL mechanism in use.
 118
 119    Some SASL mechanisms support sending an "empty string";
 120    FIXME we need some way to do this.
 121
 122 BEGIN Command
 123 ===
 124
 125    The BEGIN command acknowledges that the client has received an
 126    OK command from the server, and that the stream of messages
 127    is about to begin.
 128
 129    The first octet received by the server after the \r\n of the BEGIN
 130    command from the client MUST be the first octet of the
 131    authenticated/encrypted stream of D-BUS messages.
 132
 133 REJECTED Command
 134 ===
 135
 136    The REJECTED command indicates that the current authentication
 137    exchange has failed, and further exchange of DATA is inappropriate.
 138    The client would normally try another mechanism, or try providing
 139    different responses to challenges.
 140
 141    Optionally, the REJECTED command has a space-separated list of
 142    available auth mechanisms as arguments. If a server ever provides
 143    a list of supported mechanisms, it MUST provide the same list
 144    each time it sends a REJECTED message. Clients are free to
 145    ignore all lists received after the first.
 146
 147 OK Command
 148 ===
 149
 150    The OK command indicates that the client has been authenticated,
 151    and that further communication will be a stream of D-BUS messages
 152    (optionally encrypted, as negotiated) rather than this protocol.
 153
 154    The first octet received by the client after the \r\n of the OK
 155    command MUST be the first octet of the authenticated/encrypted
 156    stream of D-BUS messages.
 157
 158    The client MUST respond to the OK command by sending a BEGIN
 159    command, followed by its stream of messages, or by disconnecting.
 160    The server MUST NOT accept additional commands using this protocol
 161    after the OK command has been sent.
 162
 163 ERROR Command
 164 ===
 165
 166    The ERROR command indicates that either server or client did not
 167    know a command, does not accept the given command in the current
 168    context, or did not understand the arguments to the command. This
 169    allows the protocol to be extended; a client or server can send a
 170    command present or permitted only in new protocol versions, and if
 171    an ERROR is received instead of an appropriate response, fall back
 172    to using some other technique.
 173
 174    If an ERROR is sent, the server or client MUST continue as if the
 175    command causing the ERROR had never been received.
 176
 177 Example of successful magic cookie authentication
 178 ===
 179
 180 (MAGIC_COOKIE is a made up mechanism)
 181
 182   C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
 183   S: OK
 184   C: BEGIN
 185
 186 Example of finding out mechanisms then picking one
 187 ===
 188
 189   C: AUTH
 190   S: REJECTED KERBEROS_V4 SKEY
 191   C: AUTH SKEY bW9yZ2Fu
 192   S: DATA OTUgUWE1ODMwOA==
 193   C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
 194   S: OK
 195   C: BEGIN
 196
 197 Example of client sends unknown command then falls back to regular auth
 198 ===
 199
 200   C: FOOBAR
 201   S: ERROR
 202   C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
 203   S: OK
 204   C: BEGIN
 205
 206 Example of server doesn't support initial auth mechanism
 207 ===
 208
 209   C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
 210   S: REJECTED KERBEROS_V4 SKEY
 211   C: AUTH SKEY bW9yZ2Fu
 212   S: DATA OTUgUWE1ODMwOA==
 213   C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
 214   S: OK
 215   C: BEGIN
 216
 217 Example of wrong password or the like followed by successful retry
 218 ===
 219
 220   C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
 221   S: REJECTED KERBEROS_V4 SKEY
 222   C: AUTH SKEY bW9yZ2Fu
 223   S: DATA OTUgUWE1ODMwOA==
 224   C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
 225   S: REJECTED
 226   C: AUTH SKEY bW9yZ2Fu
 227   S: DATA OTUgUWE1ODMwOA==
 228   C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
 229   S: OK
 230   C: BEGIN
 231
 232 Example of skey canceled and restarted
 233 ===
 234
 235   C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
 236   S: REJECTED KERBEROS_V4 SKEY
 237   C: AUTH SKEY bW9yZ2Fu
 238   S: DATA OTUgUWE1ODMwOA==
 239   C: CANCEL
 240   S: REJECTED
 241   C: AUTH SKEY bW9yZ2Fu
 242   S: DATA OTUgUWE1ODMwOA==
 243   C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
 244   S: OK
 245   C: BEGIN
 246