D-BUS Authentication === This document defines a small plain-text protocol used to perform authentication and negotiate a security layer before the flow of D-BUS messages begins. This protocol is intended to be a profile of the Simple Authentication and Session Layer [SASL]. This document is loosely based on the POP3 SASL profile by John Myers. Conventions Used in this Document === In examples, "C:" and "S:" indicate lines sent by the client and server respectively. The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as defined in "Key words for use in RFCs to Indicate Requirement Levels" [RFC 2119] Protocol Overview === The protocol is a line-based protocol, where each line ends with \r\n. Each line begins with an all-caps ASCII command name containing only the character range [A-Z], a space, then any arguments for the command, then the \r\n ending the line. The protocol is case-sensitive. All bytes must be in the ASCII character set. Commands from the client to the server are as follows: AUTH [mechanism] [initial-response] CANCEL BEGIN DATA ERROR [human-readable error explanation] From server to client are as follows: REJECTED OK DATA ERROR Special credentials-passing nul byte === Immediately after connecting to the server, the client must send a single nul byte. This byte may be accompanied by credentials information on some operating systems that use sendmsg() with SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain sockets. However, the nul byte MUST be sent even on other kinds of socket, and even on operating systems that do not require a byte to be sent in order to transmit credentials. The text protocol described in this document begins after the single nul byte. If the first byte received from the client is not a nul byte, the server may disconnect that client. A nul byte in any context other than the initial byte is an error; the protocol is ASCII-only. The credentials sent along with the nul byte may be used with the SASL mechanism EXTERNAL. AUTH Command === If an AUTH command has no arguments, it is a request to list available mechanisms. The server SHOULD respond with a REJECTED command listing the mechanisms it understands. If an AUTH command specifies a mechanism, and the server supports said mechanism, the server SHOULD begin exchanging SASL challenge-response data with the client using DATA commands. If the server does not support the mechanism given in the AUTH command, it SHOULD send a REJECTED command listing the mechanisms it does support. If the [initial-response] argument is provided, it is intended for use with mechanisms that have no initial challenge (or an empty initial challenge), as if it were the argument to an initial DATA command. If the selected mechanism has an initial challenge, the server should reject authentication by sending REJECTED. If authentication succeeds after exchanging DATA commands, an OK command should be sent to the client. The first octet received by the client after the \r\n of the OK command MUST be the first octet of the authenticated/encrypted stream of D-BUS messages. The first octet received by the server after the \r\n of the BEGIN command from the client MUST be the first octet of the authenticated/encrypted stream of D-BUS messages. CANCEL Command === At any time up to sending the BEGIN command, the client may send a CANCEL command. On receiving the CANCEL command, the server MUST send a REJECTED command and abort the current authentication exchange. DATA Command === The DATA command may come from either client or server, and simply contains a base64-encoded block of data to be interpreted according to the SASL mechanism in use. Some SASL mechanisms support sending an "empty string"; FIXME we need some way to do this. BEGIN Command === The BEGIN command acknowledges that the client has received an OK command from the server, and that the stream of messages is about to begin. The first octet received by the server after the \r\n of the BEGIN command from the client MUST be the first octet of the authenticated/encrypted stream of D-BUS messages. REJECTED Command === The REJECTED command indicates that the current authentication exchange has failed, and further exchange of DATA is inappropriate. The client would normally try another mechanism, or try providing different responses to challenges. Optionally, the REJECTED command has a space-separated list of available auth mechanisms as arguments. If a server ever provides a list of supported mechanisms, it MUST provide the same list each time it sends a REJECTED message. Clients are free to ignore all lists received after the first. OK Command === The OK command indicates that the client has been authenticated, and that further communication will be a stream of D-BUS messages (optionally encrypted, as negotiated) rather than this protocol. The first octet received by the client after the \r\n of the OK command MUST be the first octet of the authenticated/encrypted stream of D-BUS messages. The client MUST respond to the OK command by sending a BEGIN command, followed by its stream of messages, or by disconnecting. The server MUST NOT accept additional commands using this protocol after the OK command has been sent. ERROR Command === The ERROR command indicates that either server or client did not know a command, does not accept the given command in the current context, or did not understand the arguments to the command. This allows the protocol to be extended; a client or server can send a command present or permitted only in new protocol versions, and if an ERROR is received instead of an appropriate response, fall back to using some other technique. If an ERROR is sent, the server or client MUST continue as if the command causing the ERROR had never been received. Example of successful magic cookie authentication === (MAGIC_COOKIE is a made up mechanism) C: AUTH MAGIC_COOKIE BsAY3g4gBNo= S: OK C: BEGIN Example of finding out mechanisms then picking one === C: AUTH S: REJECTED KERBEROS_V4 SKEY C: AUTH SKEY bW9yZ2Fu S: DATA OTUgUWE1ODMwOA== C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== S: OK C: BEGIN Example of client sends unknown command then falls back to regular auth === C: FOOBAR S: ERROR C: AUTH MAGIC_COOKIE BsAY3g4gBNo= S: OK C: BEGIN Example of server doesn't support initial auth mechanism === C: AUTH MAGIC_COOKIE BsAY3g4gBNo= S: REJECTED KERBEROS_V4 SKEY C: AUTH SKEY bW9yZ2Fu S: DATA OTUgUWE1ODMwOA== C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== S: OK C: BEGIN Example of wrong password or the like followed by successful retry === C: AUTH MAGIC_COOKIE BsAY3g4gBNo= S: REJECTED KERBEROS_V4 SKEY C: AUTH SKEY bW9yZ2Fu S: DATA OTUgUWE1ODMwOA== C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== S: REJECTED C: AUTH SKEY bW9yZ2Fu S: DATA OTUgUWE1ODMwOA== C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== S: OK C: BEGIN Example of skey canceled and restarted === C: AUTH MAGIC_COOKIE BsAY3g4gBNo= S: REJECTED KERBEROS_V4 SKEY C: AUTH SKEY bW9yZ2Fu S: DATA OTUgUWE1ODMwOA== C: CANCEL S: REJECTED C: AUTH SKEY bW9yZ2Fu S: DATA OTUgUWE1ODMwOA== C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA== S: OK C: BEGIN