byte     0        1                  9      (10 bytes total)
     +--------+--------+---...---+--------+
     | spec-  |       SID[i]{0..8}        |
     |  byte  |                           |
     +--------+--------+---...---+--------+

Figure 2: ENO suboption used to initiate session resumption. The spec-byte contains a tcpcrypt cs value and v = 1.

The active opener MUST use the lowest value of i that has not already been used to successfully negotiate resumption with the same host and for the same pre-session key ss[0].

A host SHOULD also include ENO suboptions describing the key-agreement schemes it supports in addition to the resume suboption, so as to fall back to full key exchange in the event that resumption fails. Implementations MUST NOT send more than one resumption suboption for the same cs value in the same SYN segment.

If the passive opener recognizes the prefix of SID[i] and knows ss[i], it SHOULD (with exceptions specified below) respond with an ENO option containing an empty resumption suboption with matching spec identifier; that is, a suboption whose initial byte gives the cs value from host A's resumption suboption and sets v = 1, but whose contents are empty. (The only way to encode this is as the last ENO suboption.)

Otherwise, the passive opener SHOULD inspect any other ENO suboptions in hopes of negotiating a fresh key exchange as described in Section 3.3.

A host MUST ignore a resumption suboption if has successfully negotiated resumption in the past, in either role, 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 ss[0] is only used 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.

Hosts MUST NOT send, and upon receipt MUST ignore, an empty resumption suboption in a SYN-only segment.

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.

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 key ss[0], or with k_ba. Thus, which keys a host uses to send segments is not affected by the role it plays in the current connection: it depends only on whether the host played the "A" or "B" role in the initial 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. A recommended interface is described in Section 10.

The session ID required by TCP-ENO and exposed to applications is constructed in the same way for resumed sessions as it is for fresh ones, as described above in Section 3.3. In particular, the first byte of the session ID is the first byte of the current connection's negotiated suboption, which means the byte will contain v = 1; and the remainder is SID[i], the bare session ID for the resumed session.

3.5. Data encryption and authentication

Following key exchange (or its omission via session caching), 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.3.

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 "plaintext" value, which is then encrypted to yield a frame's ciphertext field. Chunks must be small enough that the ciphertext (whose length depends on the AEAD cipher used, and is generally 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 zero-indexed 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.) Because it is strictly necessary for the security of the AEAD algorithm, an implementation MUST NOT ever transmit distinct frames with the same nonce value under the same encryption key. In particular, a retransmitted TCP segment MUST contain the same payload bytes for the same TCP sequence numbers, and a host MUST NOT transmit more than 2^64 bytes in the underlying TCP datastream (which would cause the offset field to wrap) before re-keying.

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.3. 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 MUST either ignore the frame or terminate the connection.

3.6. 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.7. 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 that 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; that is, it should not initiate re-keying with an empty application frame more than once while its record of the remote host's current generation number is less than its own.

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.8. Keep-alive

Instead of using TCP Keep-Alives to verify that the remote endpoint is still alive, tcpcrypt implementations SHOULD employ the re-keying mechanism, as follows. When necessary, a host SHOULD probe the liveness of its peer by initiating re-keying as described in Section 3.7, 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).

Implementations MAY use TCP Keep-Alives for purposes that do not require endpoint authentication, as discussed in Section 9.2.

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 described in Section 5.

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 field PK_A. 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 described in Section 5.

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

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 in the previous section will generally be greater than plen, as the ciphertext produced by the authenticated-encryption scheme must both encrypt the application data and provide a way to verify its integrity.)

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

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 |     FRAME_NONCE_MAGIC     |
   +------+------+------+------+
 4 |                           |
   +           offset          +
 8 |                           |
   +------+------+------+------+

The 4-byte magic constant is defined in Table 3. The 8-byte offset field contains an integer in big-endian format. Its value is specified in Section 3.5.

5. Key agreement schemes

The encryption spec negotiated via TCP-ENO may indicate the use of one of the key-agreement schemes named in Table 1. For example, TCPCRYPT_ECDHE_P256 names the tcpcrypt protocol with key-agreement scheme ECDHE-P256.

All schemes listed there use HKDF-Expand-SHA256 as the CPRF, and these lengths for nonces and session keys:

N_A_LEN: 32 bytes
N_B_LEN: 32 bytes
K_LEN:   32 bytes

Key-agreement schemes ECDHE-P256 and ECDHE-P521 employ the ECSVDP-DH secret value derivation primitive defined in [ieee1363]. The named curves are defined in [nist-dss]. When the public-key values PK_A and PK_B are transmitted as described in Section 4.1, they are encoded with the "Elliptic Curve Point to Octet String Conversion Primitive" described in Section E.2.3 of [ieee1363], and are prefixed by a two-byte length in big-endian format:

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

Implementations SHOULD encode these pubkey values in "compressed format", and MUST accept values encoded in "compressed", "uncompressed" or "hybrid" formats.

Key-agreement schemes ECDHE-Curve25519 and ECDHE-Curve448 use the functions X25519 and X448, respectively, to perform the Diffie-Helman protocol as described in [RFC7748]. When using these ciphers, public-key values PK_A and PK_B are transmitted directly with no length prefix: 32 bytes for Curve25519, and 56 bytes for Curve448.

A tcpcrypt implementation MUST support at least the schemes ECDHE-P256 and ECDHE-P521, although system administrators need not enable them.

6. AEAD algorithms

Specifiers and key-lengths for AEAD algorithms are given in Table 2. The algorithms AEAD_AES_128_GCM and AEAD_AES_256_GCM are specified in [RFC5116]. The algorithm AEAD_CHACHA20_POLY1305 is specified in [RFC7539].

7. IANA considerations

Tcpcrypt's spec identifiers (cs values) will need to be added to IANA's ENO suboption registry, as follows: