| 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. |