thrift-sasl-spec.txt

A Thrift SASL message shall be a byte array of the following form:

| 1-byte status code | 4-byte payload length | variable-length payload |

The length fields shall be interpreted as integers, with the high byte sent
first. This indicates the length of the field immediately following it, not
including the status code or the length bytes.

The possible status codes are:

0x01 - START - Hello, let's go on a date.
0x02 - OK - Everything's been going alright so far, let's see each other again.
0x03 - BAD - I understand what you're saying. I really do. I just don't like it. We have to break up.
0x04 - ERROR - We can't go on like this. It's like you're speaking another language.
0x05 - COMPLETE - Will you marry me?

The Thrift SASL communication will proceed as follows:

1. The client is configured at instantiation of the transport with a single
underlying SASL security mechanism that it supports.

2. The server is configured with a mapping of underlying security mechanism
name -> mechanism options.

3. At connection time, the client will initiate communication by sending the
server a START message. The payload of this message will be the name of the
underlying security mechanism that the client would like to use.
This mechanism name shall be 1-20 characters in length, and follow the
specifications for SASL mechanism names specified in RFC 2222.

4. The server receives this message and, if the mechanism name provided is
among the set of mechanisms this server transport is configured to accept,
appropriate initialization of the underlying security mechanism may take place.
If the mechanism name is not one which the server is configured to support, the
server shall return the BAD byte, followed by a 4-byte, potentially zero-value
message length, followed by the potentially zero-length payload which may be a
status code or message indicating failure. No further communication may take
place via this transport. If the mechanism name is one which the server
supports, then proceed to step 5.

5. Following the START message, the client must send another message containing
the "initial response" of the chosen SASL implementation. The client may send
this message piggy-backed on the "START" message of step 3. The message type
of this message must be either "OK" or "COMPLETE", depending on whether the
SASL implementation indicates that this side of the authentication has been
satisfied.

6. The server then provides the byte array of the payload received to its
underlying security mechanism. A challenge is generated by the underlying
security mechanism on the server, and this is used as the payload for a message
sent to the client. This message shall consist of an OK byte, followed by the
non-zero message length word, followed by the payload.

7. The client receives this message from the server and passes the payload to
its underlying security mechanism to generate a response. The client then sends
the server an OK byte, followed by the non-zero-value length of the response,
followed by the bytes of the response as the payload.

8. Steps 6 and 7 are repeated until both security mechanisms are satisfied with
the challenge/response exchange. When either side has completed its security
protocol, its next message shall be the COMPLETE byte, followed by a 4-byte
potentially zero-value length word, followed by a potentially zero-length
payload. This payload will be empty except for those underlying security
mechanisms which provide additional data with success.

If at any point in time either side is able to interpret the challenge or
response sent by the other, but is dissatisfied with the contents thereof, this
side should send the other a BAD byte, followed by a 4-byte potentially
zero-value length word, followed by an optional, potentially zero-length
message encoded in UTF-8 indicating failure. This message should be passed to
the protocol above the thrift transport by whatever mechanism is appropriate
and idiomatic for the particular language these thrift bindings are for.

If at any point in time either side fails to interpret the challenge or
response sent by the other, this side should send the other an ERROR byte,
followed by a 4-byte potentially zero-value length word, followed by an
optional, potentially zero-length message encoded in UTF-8. This message should
be passed to the protocol above the thrift transport by whatever mechanism is
appropriate and idiomatic for the particular language these thrift bindings are
for.

If step 8 completes successfully, then the communication is considered
authenticated and subsequent communication may commence.

If step 8 fails to complete successfully, then no further communication may
take place via this transport.

8. All writes to the underlying transport must be prefixed by the 4-byte length
of the payload data, followed by the payload. All reads from this transport
should read the 4-byte length word, then read the full quantity of bytes
specified by this length word.

If no SASL QOP (quality of protection) is negotiated during steps 6 and 7, then
all subsequent writes to/reads from this transport are written/read unaltered,
save for the length prefix, to the underlying transport.

If a SASL QOP is negotiated, then this must be used by the Thrift transport for
all subsequent communication. This is done by wrapping subsequent writes to the
transport using the underlying security mechanism, and unwrapping subsequent
reads from the underlying transport. Note that in this case, the length prefix
of the write to the underlying transport is the length of the data after it has
been wrapped by the underlying security mechanism. Note that the complete
message must be read before giving this data to the underlying security
mechanism for unwrapping.

If at any point in time reading of a message fails either because of a
malformed length word or failure to unwrap by the underlying security
mechanism, then all further communication on this transport must cease.