Data Transmission Over Out-of-Band Alternative Tranports for AFS-3

5.1. Rx split stream contents

The contents of the Rx split stream for both FetchDataOOB and StoreDataOOB are identical. The only data that appears on the split stream is a single AFSOOB_Challenge union, encoded in XDR, which is sent from the server to the client. This structure is specified as thus in RPC-L:¶

const AFSTCP_IPMAX = 128;
const AFSOOB_v1 = 1;

struct AFSTCP_IPv4 {
  afs_uint32 host;
  afs_uint16 port;
};

struct AFSOOB_v1_challenge {
  struct AFSTCP_IPv4 addrs<AFSTCP_IPMAX>;
};

union AFSOOB_Challenge switch (afs_uint32 type) {
  case AFSOOB_v1:
    struct AFSOOB_v1_challenge challenge;
};

AFSOOB_Challenge is a union, where the discriminant just dictates a logical "version" of the out-of-band challenge structure. Future revisions of this AFS-3 extension may involve more data in the challenge, which may be specified at a future date. Currently, only data for the AFSOOB_v1 challenge is defined, which is defined in the AFSOOB_v1_challenge struct as follows:¶

addrs

This is an array containing pairs of IPv4 addresses and TCP ports that the client may attempt to connect to in order to initiate a TCP transfer. Several addresses MAY be specified, which SHOULD be attempted in order by the client. The "host" field indicates the IPv4 address to connect to. The server MAY specify an IPv4 address of 0.0.0.0, which indicates that the client MUST attempt to connect to the same IPv4 address that it is using for the associated RxUDP connection. The "port" field specifies the TCP port number to connect to.¶

5.2. XDR over TCP format

A few XDR-encoded structures are sent over the relevant TCP stream during a FetchDataTCP or StoreDataTCP call. Since the TCP stream is shared by both XDR-marshalled data and raw file data, in order to simplify processing, every logical block of XDR is prefixed by a length value. This "length" is a 32-bit unsigned integer, and is sent in network byte order over the TCP stream. Immediately following it is "length" number of octets representing the XDR stream. Anywhere in this document that refers to an XDR stream being transmitted over a TCP connection, this format MUST be used. Note that we do not use the Record Marking Standard from [RFC5531] section 11 for encapsulating XDR over TCP.¶

5.3. TCP stream negotiation

Once a client has received the challenge described in Section 5.1 over the relevant Rx split stream, the client opens a TCP connection to the fileserver (or the client MAY reuse an extant TCP connection, see Section 5.6). If the client succeeds in creating a connection, the client sends a response to the given challenge immediately on the TCP stream. The response consists of a single AFSTCP_Response union sent from the client to the server. The AFSTCP_Response union is defined as thus in RPC-L:¶

const AFSTCP_RXNULL = 0;
const AFSTCP_RXKAD = 2;

struct AFSTCP_v1_uniq {
  afs_uint32 host;
  afs_uint32 portAndServiceId;
  afs_uint32 epoch;
  afs_uint32 cid;
  afs_uint32 callNumber;
};

union AFSTCP_v1_private switch (afs_uint32 securityIndex) {
  case AFSTCP_RXNULL:
    void;
  case AFSTCP_RXKAD:
    struct AFSTCP_v1_rxkad encrypted;
};

struct AFSTCP_v1_response {
  struct AFSTCP_v1_uniq uniq;
  union AFSTCP_v1_private private;
};

union AFSTCP_Response switch (afs_uint32 type) {
  case AFSOOB_v1:
    struct AFSTCP_v1_response response;
};

AFSTCP_Response is a union, where the discriminant just dictates a logical "version" of the OOB out of band response structure. Future revisions of this AFS-3 extension may involve more data in the response, which may be specified at a future date. Currently, only data for the AFSOOB_v1 response is defined, which is defined in the AFSTCP_v1_response struct as follows:¶

uniq

The contents of this structure are defined immediately below.¶

private

This contains data specific to the security index used in the Rx connection of the associated Rx call. The discriminant is that security index, and it MUST match the security index of the Rx connection for the associated call. For unauthenticated connections (rxnull), this is an empty structure. For connections authenticated with rxkad, this is an AFSTCP_v1_rxkad structure, which is defined in Section 5.4.¶

The AFSTCP_v1_uniq structure is used to identify which Rx call this connection is to be associated with. It is defined as follows:¶

host

The fileserver IPv4 address the client is using to connect to the relevant fileserver.¶

portAndServiceId

The least-significant 16 bits of this integer are the TCP port the client is using to connect to the relevant fileserver. The most-significant 16 bits are the service Id used in the relevant Rx call.¶

epoch

The Rx connection epoch for the associated connection.¶

cid

The connection Id for the associated Rx call channel and connection.¶

callNumber

The call number of the associated Rx call.¶

The client MUST fill this structure with the values matching the values in the corresponding Rx call. The server MUST verify that the values of the structure do correspond to an existing FetchDataTCP or StoreDataTCP Rx call, and that the given host and port are valid for the fileserver.¶

5.4. rxkad challenge response

The rxkad-specific portion of the challenge response structure transmitted over the TCP connection is described here. The entire structure is encrypted via fcrypt in ECB mode with the session key schedule and initialization vector of the Rx connection of the associated Rx call, and must be decrypted before its contents can be interpreted. The structure is defined in RPC-L as thus:¶

struct AFSTCP_v1_rxkad {
  struct AFSTCP_v1_uniq uniq;
  afs_uint32 seclevel;
};

After being decrypted, the structure contents are defined as follows:¶

uniq

This MUST be identical to the uniquifier specified in the encompassing AFSTCP_v1_response structure, as defined in Section 5.3.¶

seclevel

This corresponds to the "security level" that exists in rxkad. Currently, this field must always be 0 (rxkad_clear), and any other value MUST immediately cause an error to be raised. In the future, it may be possible to specify other security levels here which indicate that the file data should be encrypted according to the analogous rxkad security level, assuming the rxkad security index is specified.¶

If the uniquifier in this structure does not exactly match the uniquifier in the parent AFSTCP_v1_response structure, the TCP connection MUST be immediately closed and considered invalid. The invalid TCP connection SHOULD just be ignored, and thus the associated Rx call SHOULD NOT be aborted or terminated, and the server SHOULD continue to listen for TCP connections until a timeout is reached or the client aborts the Rx call. This is so unauthenticated attackers do not cause the Rx call to be aborted unnecessarily.¶

5.6. TCP Connection Caching

Once a transfer has completed successfully, the TCP connection used does not need to be closed. The client and server MAY keep the connection open for use with a future transfer if they support the functionality in this section. A fileserver that supports this will, after a transfer is complete, treat the TCP connection as if it were a newly-accepted TCP connection. That is, the server will then wait for the connection to receive an AFSTCP_Response structure, or will time out the connection after an implementation-defined amount of time.¶

If the client wishes to make use of connection caching, it may also keep its end of the connection open, and may use that connection for a future transfer. All of the negotiation steps are the same as normal, with the sole exception that the client reuses the TCP connection instead of making a new one. Since all authentication negotiation occurs again, the cached TCP connections may be used for any user with any authentication credentials. However, the client MUST ensure that the TCP is connected to an address that is valid according to the AFSTCP_Challenge received from the fileserver.¶

The caching of TCP connections is strictly OPTIONAL for both client and server. If either client or server does not support this, they may simply close the TCP connection after a successful transfer. If a client closes such a connection when the server supports caching, the server will take notice when listening for an AFSTCP_Response structure, and will just close its end of the connection. If the server closes such a connection when the client supports caching, the client will notice when it tries to reuse the connection; in which case, the client SHOULD simply discard the cached connection and create a new one.¶