byte     0        1                  9
     +--------+--------+---...---+--------+
     | Opt =  |       SID[i]{0..8}        |
     | resume |                           |
     +--------+--------+---...---+--------+

Figure 2: ENO suboption used to initiate session resumption

Above, the resume value is the byte whose lower 7 bits are TCPCRYPT_RESUME and whose top bit v is 1 (indicating variable-length data follows). The remainder of the suboption is filled with the first nine bytes of the Session ID SID[i].

A host SHOULD also include ENO suboptions describing the key-agreement schemes it supports in addition to a resume suboption, so as to fall back to full key exchange in the event that session resumption fails.

Which symmetric keys a host uses for transmitted segments is determined by its role in the original session ss[0]. It does not depend on the role it plays in the current session. For example, if a host had the "A" role in the first session, then it uses k_ab for sending segments and k_ba for receiving.

After using ss[i] to compute mk[0], implementations SHOULD compute and cache ss[i+1] for possible use by a later session, then erase ss[i] from memory. Hosts SHOULD keep ss[i+1] around for a period of time until it is used or the memory needs to be reclaimed. Hosts SHOULD NOT write a cached ss[i+1] value to non-volatile storage.

It is an implementation-specific issue as to how long ss[i+1] should be retained if it is unused. If the passive opener evicts it from cache before the active opener does, the only cost is the additional ten bytes to send the resumption suboption in the next connection. The behavior then falls back to a normal public-key handshake.

The active opener MUST use the lowest value of i that has not already appeared in a resumption suboption exchanged with the same host and for the same pre-session seed.

If the passive opener recognizes SID[i] and knows ss[i], it SHOULD respond with an ENO option containing a dataless resumption suboption; that is, the suboption whose cs value is TCPCRYPT_RESUME and whose v bit is zero.

If the passive opener does not recognize SID[i], or SID[i] is not valid or has already been used, the passive opener SHOULD inspect any other ENO suboptions in hopes of negotiating a fresh key exchange as described in Section 3.4.

When two hosts have previously negotiated a tcpcrypt session, either host may initiate session resumption regardless of which host was the active opener or played the "A" role in the previous session. However, a given host must either encrypt with k_ab for all sessions derived from the same pre-session seed, or k_ba. Thus, which keys a host uses to send segments depends only whether the host played the "A" or "B" role in the initial session that used ss[0]; it is not affected by which host was the active opener transmitting the SYN segment containing a resumption suboption.

A host MUST ignore a resumption suboption if it has previously sent or received one with the same SID[i]. In the event that two hosts simultaneously send SYN segments to each other with the same SID[i], but the two segments are not part of a simultaneous open, both connections will have to revert to public key cryptography. To avoid this limitation, implementations MAY choose to implement session caching such that a given pre-session key is only good for either passive or active opens at the same host, not both.

In the case of simultaneous open where TCP-ENO is able to establish asymmetric roles, two hosts that simultaneously send SYN segments with resumption suboptions containing the same SID[i] may resume the associated session.

Implementations that perform session caching MUST provide a means for applications to control session caching, including flushing cached session secrets associated with an ESTABLISHED connection or disabling the use of caching for a particular connection.

3.6. Data encryption and authentication

Following key exchange, all further communication in a tcpcrypt-enabled connection is carried out within delimited application frames that are encrypted and authenticated using the agreed keys.

This protection is provided via algorithms for Authenticated Encryption with Associated Data (AEAD). The particular algorithms that may be used are listed in Table 2. One algorithm is selected during the negotiation described in Section 3.4.

The format of an application frame is specified in Section 4.2. A sending host breaks its stream of application data into a series of chunks. Each chunk is placed in the data portion of a frame's "plaintext" value, which is then encrypted to yield the frame's ciphertext field. Chunks must be small enough that the ciphertext (slightly longer than the plaintext) has length less than 2^16 bytes.

An "associated data" value (see Section 4.2.2) is constructed for the frame. It contains the frame's control field and the length of the ciphertext.

A "frame nonce" value (see Section 4.2.3) is also constructed for the frame (but not explicitly transmitted), containing an offset field whose integer value is the byte-offset of the beginning of the current application frame in the underlying TCP datastream. (That is, the offset in the framing stream, not the plaintext application stream.) As the security of the AEAD algorithm depends on this nonce being used to encrypt at most one distinct plaintext value, an implementation MUST NOT ever transmit distinct frames at the same location in the underlying TCP datastream.

With reference to the "AEAD Interface" described in Section 2 of [RFC5116], tcpcrypt invokes the AEAD algorithm with the secret key K set to k_ab or k_ba, according to the host's role as described in Section 3.4. The plaintext value serves as P, the associated data as A, and the frame nonce as N. The output of the encryption operation, C, is transmitted in the frame's ciphertext field.

When a frame is received, tcpcrypt reconstructs the associated data and frame nonce values (the former contains only data sent in the clear, and the latter is implicit in the TCP stream), and provides these and the ciphertext value to the the AEAD decryption operation. The output of this operation is either P, a plaintext value, or the special symbol FAIL. In the latter case, the implementation MAY either ignore the frame or terminate the connection.

3.7. TCP header protection

The ciphertext field of the application frame contains protected versions of certain TCP header values.

When URGp is set, the urgent value indicates an offset from the current frame's beginning offset; the sum of these offsets gives the index of the last byte of urgent data in the application datastream.

When FINp is set, it indicates that the sender will send no more application data after this frame. A receiver MUST ignore the TCP FIN flag and instead wait for FINp to signal to the local application that the stream is complete.

3.8. Re-keying

Re-keying allows hosts to wipe from memory keys that could decrypt previously transmitted segments. It also allows the use of AEAD ciphers that can securely encrypt only a bounded number of messages under a given key.

We refer to the two encryption keys (k_ab, k_ba) as a key-set. We refer to the key-set generated by mk[i] as the key-set with generation number i within a session. Each host maintains a current generation number that it uses to encrypt outgoing frames. Initially, the two hosts have current generation number 0.

When a host has just incremented its current generation number and has used the new key-set for the first time to encrypt an outgoing frame, it MUST set the frame's rekey field (see Section 4.2) to 1. It MUST set this field to zero in all other cases.

A host MAY increment its generation number beyond the highest generation it knows the other side to be using. We call this action initiating re-keying.

A host SHOULD NOT initiate more than one concurrent re-key operation if it has no data to send.

On receipt, a host increments its record of the remote host's current generation number if and only if the rekey field is set to 1.

If a received frame's generation number is greater than the receiver's current generation number, the receiver MUST immediately increment its current generation number to match. After incrementing its generation number, if the receiver does not have any application data to send, it MUST send an empty application frame with the rekey field set to 1.

When retransmitting, implementations must always transmit the same bytes for the same TCP sequence numbers. Thus, a frame in a retransmitted segment MUST always be encrypted with the same key as when it was originally transmitted.

Implementations SHOULD delete older-generation keys from memory once they have received all frames they will need to decrypt with the old keys and have encrypted all outgoing frames under the old keys.

3.9. Keep-alive

Many hosts implement TCP Keep-Alives [RFC1122] as an option for applications to ensure that the other end of a TCP connection still exists even when there is no data to be sent. A TCP Keep-Alive segment carries a sequence number one prior to the beginning of the send window, and may carry one byte of "garbage" data. Such a segment causes the remote side to send an acknowledgment.

Unfortunately, tcpcrypt cannot cryptographically verify Keep-Alive acknowledgments. Hence, an attacker could prolong the existence of a session at one host after the other end of the connection no longer exists. (Such an attack might prevent a process with sensitive data from exiting, giving an attacker more time to compromise a host and extract the sensitive data.)

Instead of TCP Keep-Alives, tcpcrypt implementations SHOULD employ the re-keying mechanism to stimulate the remote host to send verifiably fresh and authentic data. When required, a host SHOULD probe the liveness of its peer by initiating re-keying as described in Section 3.8, and then transmitting a new frame (with zero-length application data if necessary). A host receiving a frame whose key generation number is greater than its current generation number MUST increment its current generation number and MUST immediately transmit a new frame (with zero-length application data, if necessary).

4. Encodings

This section provides byte-level encodings for values transmitted or computed by the protocol.

4.1. Key exchange messages

The INIT1 message has the following encoding:

byte   0       1       2       3
   +-------+-------+-------+-------+
   |          INIT1_MAGIC          |
   |                               |
   +-------+-------+-------+-------+

           4        5      6       7
       +-------+-------+-------+-------+
       |          message_len          |
       |              = M              |
       +-------+-------+-------+-------+

           8
       +--------+-------+-------+---...---+-------+
       |nciphers|sym-   |sym-   |         |sym-   |
       | =K+1   |cipher0|cipher1|         |cipherK|
       +--------+-------+-------+---...---+-------+

          K + 10                    K + 10 + N_A_LEN
           |                         |
           v                         v
       +-------+---...---+-------+-------+---...---+-------+
       |           N_A           |          PK_A           |
       |                         |                         |
       +-------+---...---+-------+-------+---...---+-------+

                           M - 1
       +-------+---...---+-------+
       |          ignored        |
       |                         |
       +-------+---...---+-------+

The constant INIT1_MAGIC is defined in Table 3. The four-byte field message_len gives the length of the entire INIT1 message, encoded as a big-endian integer. The nciphers field contains an integer value that specifies the number of one-byte symmetric-cipher identifiers that follow. The sym-cipher bytes identify cryptographic algorithms in Table 2. The length N_A_LEN and the length of PK_A are both determined by the negotiated key-agreement scheme, as shown in Figure 3.

When sending INIT1, implementations of this protocol MUST omit the field ignored; that is, they must construct the message such that its end, as determined by message_len, coincides with the end of the PK_A field. When receiving INIT1, however, implementations MUST permit and ignore any bytes following PK_A.

The INIT2 message has the following encoding:

byte   0       1       2       3
   +-------+-------+-------+-------+
   |          INIT2_MAGIC          |
   |                               |
   +-------+-------+-------+-------+


           4        5      6       7       8
       +-------+-------+-------+-------+-------+
       |          message_len          |sym-   |
       |              = M              |cipher |
       +-------+-------+-------+-------+-------+

           9                        9 + N_B_LEN
           |                         |
           v                         v
       +-------+---...---+-------+-------+---...---+-------+
       |           N_B           |          PK_B           |
       |                         |                         |
       +-------+---...---+-------+-------+---...---+-------+

                           M - 1
       +-------+---...---+-------+
       |          ignored        |
       |                         |
       +-------+---...---+-------+

The constant INIT2_MAGIC is defined in Table 3. The four-byte field message_len gives the length of the entire INIT2 message, encoded as a big-endian integer. The sym-cipher value is a selection from the symmetric-cipher identifiers in the previously-received INIT1 message. The length N_B_LEN and the length of PK_B are both determined by the negotiated key-agreement scheme, as shown in Figure 3.

When sending INIT2, implementations of this protocol MUST omit the field ignored; that is, they must construct the message such that its end, as determined by message_len, coincides with the end of the PK_B field. When receiving INIT2, however, implementations MUST permit and ignore any bytes following PK_B.

4.2. Application frames

An application frame comprises a control byte and a length-prefixed ciphertext value:

byte   0       1       2       3               clen+2
   +-------+-------+-------+-------+---...---+-------+
   |control|      clen     |        ciphertext       |
   +-------+-------+-------+-------+---...---+-------+

The field clen is an integer in big-endian format and gives the length of the ciphertext field.

The byte control has this structure:

bit     7                 1       0
    +-------+---...---+-------+-------+
    |          cres           | rekey |
    +-------+---...---+-------+-------+

The seven-bit field cres is reserved; implementations MUST set these bits to zero when sending, and MUST ignore them when receiving.

The use of the rekey field is described in Section 3.8.

4.2.1. Plaintext

The ciphertext field is the result of applying the negotiated authenticated-encryption algorithm to a "plaintext" value, which has one of these two formats:

byte   0       1               plen-1
   +-------+-------+---...---+-------+
   | flags |           data          |
   +-------+-------+---...---+-------+


byte   0       1       2       3              plen-1
   +-------+-------+-------+-------+---...---+-------+
   | flags |    urgent     |          data           |
   +-------+-------+-------+-------+---...---+-------+

(Note that clen will generally be greater than plen, as the authenticated-encryption scheme attaches an integrity "tag" to the encrypted input.)

The flags byte has this structure:

bit    7    6    5    4    3    2    1    0
    +----+----+----+----+----+----+----+----+
    |            fres             |URGp|FINp|
    +----+----+----+----+----+----+----+----+

The six-bit value fres is reserved; implementations MUST set these six bits to zero when sending, and MUST ignore them when receiving.

When the URGp bit is set, it indicates that the urgent field is present, and thus that the plaintext value has the second structure variant above; otherwise the first variant is used.

The meaning of urgent and of the flag bits is described in Section 3.7.

4.2.2. Associated data

An application frame's "associated data" (which is supplied to the AEAD algorithm when decrypting the ciphertext and verifying the frame's integrity) has this format:

byte   0       1       2
   +-------+-------+-------+
   |control|     clen      |
   +-------+-------+-------+

It contains the same values as the frame's control and clen fields.

4.2.3. Frame nonce

Lastly, a "frame nonce" (provided as input to the AEAD algorithm) has this format:

byte
   +------+------+------+------+
 0 | 0x44 | 0x41 | 0x54 | 0x41 |
   +------+------+------+------+
 4 |                           |
   +           offset          +
 8 |                           |
   +------+------+------+------+

The 8-byte offset field contains an integer in big-endian format. Its value is specified in Section 3.6.

5. API extensions

Applications aware of tcpcrypt will need an API for interacting with the protocol. They can do so if implementations provide the recommended API for TCP-ENO. This section recommends several additions to that API, described in the style of socket options. However, these recommendations are non-normative:

The following options is read-only:

TCP_CRYPT_CONF:

Returns the one-byte authenticated encryption algorithm in use by the connection (as specified in Table 2).

The following option is write-only:

TCP_CRYPT_CACHE_FLUSH:

Setting this option to non-zero wipes cached session keys as specified in Section 3.5. Useful if application-level authentication discovers a man in the middle attack, to prevent the next connection from using session caching.

The following options should be readable and writable:

TCP_CRYPT_ACONF:

Set of allowed symmetric ciphers and message authentication codes this host advertises in INIT1 messages.

TCP_CRYPT_BCONF:

Order of preference of symmetric ciphers.

Finally, system administrators must be able to set the following system-wide parameters:

• Default TCP_CRYPT_ACONF value
• Default TCP_CRYPT_BCONF value
• Types, key lengths, and regeneration intervals of local host's short-lived public keys for implementations that do not use fresh ECDH parameters for each connection.

6. Key agreement schemes

The encryption spec negotiated via TCP-ENO may indicate the use of one of these key-agreement schemes:

+---------------------------+----------------------------------+
|   Encryption spec (cs)    |     Key-agreement scheme         |
+---------------------------+----------------------------------+
| TCPCRYPT_ECDHE_P256       | Cipher: ECDHE-P256               |
|                           | Extract: HKDF-Extract-SHA256     |
|                           | CPRF: HKDF-Expand-SHA256         |
|                           | N_A_LEN: 32 bytes                |
|                           | N_B_LEN: 32 bytes                |
|                           | K_LEN: 32 bytes                  |
+---------------------------+----------------------------------+
| TCPCRYPT_ECDHE_P521       | Cipher: ECDHE-P521               |
|                           | Extract: HKDF-Extract-SHA256     |
|                           | CPRF: HKDF-Expand-SHA256         |
|                           | N_A_LEN: 32 bytes                |
|                           | N_B_LEN: 32 bytes                |
|                           | K_LEN: 32 bytes                  |
+---------------------------+----------------------------------+
| TCPCRYPT_ECDHE_Curve25519 | Cipher: ECDHE-Curve25519         |
|                           | Extract: HKDF-Extract-SHA256     |
|                           | CPRF: HKDF-Expand-SHA256         |
|                           | N_A_LEN: 32 bytes                |
|                           | N_B_LEN: 32 bytes                |
|                           | K_LEN: 32 bytes                  |
+---------------------------+----------------------------------+

byte   0       1       2               L - 1
   +-------+-------+-------+---...---+-------+
   |   pubkey_len  |          pubkey         |
   |      = L      |                         |
   +-------+-------+-------+---...---+-------+