ceph/src/jaegertracing/thrift/doc/specs/thrift-sasl-spec.txt

   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.