]>
Commit | Line | Data |
---|---|---|
f67539c2 TL |
1 | A Thrift SASL message shall be a byte array of the following form: |
2 | ||
3 | | 1-byte status code | 4-byte payload length | variable-length payload | | |
4 | ||
5 | The length fields shall be interpreted as integers, with the high byte sent | |
6 | first. This indicates the length of the field immediately following it, not | |
7 | including the status code or the length bytes. | |
8 | ||
9 | The possible status codes are: | |
10 | ||
11 | 0x01 - START - Hello, let's go on a date. | |
12 | 0x02 - OK - Everything's been going alright so far, let's see each other again. | |
13 | 0x03 - BAD - I understand what you're saying. I really do. I just don't like it. We have to break up. | |
14 | 0x04 - ERROR - We can't go on like this. It's like you're speaking another language. | |
15 | 0x05 - COMPLETE - Will you marry me? | |
16 | ||
17 | The Thrift SASL communication will proceed as follows: | |
18 | ||
19 | 1. The client is configured at instantiation of the transport with a single | |
20 | underlying SASL security mechanism that it supports. | |
21 | ||
22 | 2. The server is configured with a mapping of underlying security mechanism | |
23 | name -> mechanism options. | |
24 | ||
25 | 3. At connection time, the client will initiate communication by sending the | |
26 | server a START message. The payload of this message will be the name of the | |
27 | underlying security mechanism that the client would like to use. | |
28 | This mechanism name shall be 1-20 characters in length, and follow the | |
29 | specifications for SASL mechanism names specified in RFC 2222. | |
30 | ||
31 | 4. The server receives this message and, if the mechanism name provided is | |
32 | among the set of mechanisms this server transport is configured to accept, | |
33 | appropriate initialization of the underlying security mechanism may take place. | |
34 | If the mechanism name is not one which the server is configured to support, the | |
35 | server shall return the BAD byte, followed by a 4-byte, potentially zero-value | |
36 | message length, followed by the potentially zero-length payload which may be a | |
37 | status code or message indicating failure. No further communication may take | |
38 | place via this transport. If the mechanism name is one which the server | |
39 | supports, then proceed to step 5. | |
40 | ||
41 | 5. Following the START message, the client must send another message containing | |
42 | the "initial response" of the chosen SASL implementation. The client may send | |
43 | this message piggy-backed on the "START" message of step 3. The message type | |
44 | of this message must be either "OK" or "COMPLETE", depending on whether the | |
45 | SASL implementation indicates that this side of the authentication has been | |
46 | satisfied. | |
47 | ||
48 | 6. The server then provides the byte array of the payload received to its | |
49 | underlying security mechanism. A challenge is generated by the underlying | |
50 | security mechanism on the server, and this is used as the payload for a message | |
51 | sent to the client. This message shall consist of an OK byte, followed by the | |
52 | non-zero message length word, followed by the payload. | |
53 | ||
54 | 7. The client receives this message from the server and passes the payload to | |
55 | its underlying security mechanism to generate a response. The client then sends | |
56 | the server an OK byte, followed by the non-zero-value length of the response, | |
57 | followed by the bytes of the response as the payload. | |
58 | ||
59 | 8. Steps 6 and 7 are repeated until both security mechanisms are satisfied with | |
60 | the challenge/response exchange. When either side has completed its security | |
61 | protocol, its next message shall be the COMPLETE byte, followed by a 4-byte | |
62 | potentially zero-value length word, followed by a potentially zero-length | |
63 | payload. This payload will be empty except for those underlying security | |
64 | mechanisms which provide additional data with success. | |
65 | ||
66 | If at any point in time either side is able to interpret the challenge or | |
67 | response sent by the other, but is dissatisfied with the contents thereof, this | |
68 | side should send the other a BAD byte, followed by a 4-byte potentially | |
69 | zero-value length word, followed by an optional, potentially zero-length | |
70 | message encoded in UTF-8 indicating failure. This message should be passed to | |
71 | the protocol above the thrift transport by whatever mechanism is appropriate | |
72 | and idiomatic for the particular language these thrift bindings are for. | |
73 | ||
74 | If at any point in time either side fails to interpret the challenge or | |
75 | response sent by the other, this side should send the other an ERROR byte, | |
76 | followed by a 4-byte potentially zero-value length word, followed by an | |
77 | optional, potentially zero-length message encoded in UTF-8. This message should | |
78 | be passed to the protocol above the thrift transport by whatever mechanism is | |
79 | appropriate and idiomatic for the particular language these thrift bindings are | |
80 | for. | |
81 | ||
82 | If step 8 completes successfully, then the communication is considered | |
83 | authenticated and subsequent communication may commence. | |
84 | ||
85 | If step 8 fails to complete successfully, then no further communication may | |
86 | take place via this transport. | |
87 | ||
88 | 8. All writes to the underlying transport must be prefixed by the 4-byte length | |
89 | of the payload data, followed by the payload. All reads from this transport | |
90 | should read the 4-byte length word, then read the full quantity of bytes | |
91 | specified by this length word. | |
92 | ||
93 | If no SASL QOP (quality of protection) is negotiated during steps 6 and 7, then | |
94 | all subsequent writes to/reads from this transport are written/read unaltered, | |
95 | save for the length prefix, to the underlying transport. | |
96 | ||
97 | If a SASL QOP is negotiated, then this must be used by the Thrift transport for | |
98 | all subsequent communication. This is done by wrapping subsequent writes to the | |
99 | transport using the underlying security mechanism, and unwrapping subsequent | |
100 | reads from the underlying transport. Note that in this case, the length prefix | |
101 | of the write to the underlying transport is the length of the data after it has | |
102 | been wrapped by the underlying security mechanism. Note that the complete | |
103 | message must be read before giving this data to the underlying security | |
104 | mechanism for unwrapping. | |
105 | ||
106 | If at any point in time reading of a message fails either because of a | |
107 | malformed length word or failure to unwrap by the underlying security | |
108 | mechanism, then all further communication on this transport must cease. |