doc/dbus-sasl-profile.txt

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