Heads up: this is an experimental feature and may still contain serious vulnerability, and the specification is also subject to change.
Summary
This patch implements a token conversation feature, which allows one to feed fresh access tokens for use in client authentication sessions provided by a background server process through a Unix domain or TCP socket.
The feature is turned on if those conditions are met:
SASL_XOAUTH2_CLIENT_TOKEN_CONV environment variable is set to the endpoint of the backend server.
Either the callback for SASL_CB_PASS or the interaction for SASL_CB_PASS yields an empty string or a single hyphen -.
The communication scheme between the client and server is detailed below:
Server verifies the Signature and must terminate the session if it doesn't correspond to the string. Otherwise, it responds to Client with a Signature and the protocol version which will be used in further communication.
The Signature is a 4 octet string, %x81 %x9d %x74 %x13 (same as the above). The version is a 32-bit big-endian unsigned integer. If Server has backward compatibility with Client's protocol, it is advised that it return the same protocol version as Client.
Upon reception of the response from Server, Client must terminate the session if the signature doesn't match, and may do so if the Server's protocol version doesn't meet its version.
A Packet starts with a 32-bit big-endian unsigned integer that stores the length of the packet content (length octets excluded) and is immediately followed by the packet content.
Server receives the query Packet and responds with the access token that corresponds to the authentication ID contained in the query.
Heads up: this is an experimental feature and may still contain serious vulnerability, and the specification is also subject to change.
Summary
SASL_XOAUTH2_CLIENT_TOKEN_CONV
environment variable is set to the endpoint of the backend server.SASL_CB_PASS
or the interaction forSASL_CB_PASS
yields an empty string or a single hyphen-
.SASL_XOAUTH2_CLIENT_TOKEN_CONV
environment variableIt can take a string of the following form:
Communication Protocol
The communication is done in the following phases:
Handshake Phase
Client sends a Signature and its highest available protocol version, which are concatenated, to Server.
The Signature is a 4 octet string,
%x81 %x9d %x74 %x13
. The version is a 32-bit big-endian unsigned integer.Server verifies the Signature and must terminate the session if it doesn't correspond to the string. Otherwise, it responds to Client with a Signature and the protocol version which will be used in further communication.
The Signature is a 4 octet string,
%x81 %x9d %x74 %x13
(same as the above). The version is a 32-bit big-endian unsigned integer. If Server has backward compatibility with Client's protocol, it is advised that it return the same protocol version as Client.Upon reception of the response from Server, Client must terminate the session if the signature doesn't match, and may do so if the Server's protocol version doesn't meet its version.
Client and Server step to Query Phase.
Query Phase
Client sends a Packet with the following content:
A Packet starts with a 32-bit big-endian unsigned integer that stores the length of the packet content (length octets excluded) and is immediately followed by the packet content.
Server receives the query Packet and responds with the access token that corresponds to the authentication ID contained in the query.
Client may repeat queries.