Protocol specification¶
Basic protocol design¶
fastd uses UDP as the transport protocol for its packets. UDP has been chosen instead of raw IP packets (as they are used by IPIP and 6in4 tunnels or IPsec) to simplify the deployment of multiple fastd instances on the same host using different UDP ports and allow passing through common NAT routers without explicit configuration.
The first byte of the UDP payload is used to discern the different packet types used by fastd. Since fastd v22, the following packet types are used:
0x00
Data packet (v22+)0x01
Handshake packet (pre-v22)0x02
Data packet (pre-v22)0xC8
L2TP control message header (v22+)
fastd v22 still supports the pre-v22 packet types, so communication between old and new versions is possible.
L2TP control message headers¶
Since fastd v22, all handshake packets may be prefixed with an L2TP control message header to make sure these packets are not considered data packets by the L2TP kernel code even with potential future extensions of the L2TP protocol. The basic format of this header is the following (as specified in RFC3931):
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|T|L|x|x|S|x|x|x|x|x|x|x| Ver | Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Control Connection ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Ns | Nr |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
When sending a packet with an L2TP header, the following rules apply:
- Only the T, L, and S flags are set (first byte is
0xC8
) - Ver is set to 3 (second byte is
0x03
) - Length is set to 12 (only the header itself is counted)
- Control Connection ID, Ns and Nr are unused, they are set to 0
When receiving packets, only the first two bytes are verified. Packets with unexpected values in these bytes are discarded.
When replying to a handshake packet, fastd will insert the L2TP header when the peer has signaled that it supports such packets using the L2TP_SUPPORT flag. Initial handshakes will be sent twice at the same time, once with and once without an L2TP header, so both new and old versions of fastd can be supported.
fastd v22 and newer ignore handshake packets without L2TP header when the L2TP_SUPPORT flag is set, so only one of the two handshake packets with identical content will be handled.
In addition to handshakes, data packets may be prefixed with such L2TP control message headers as well, but this is rarely useful, as it reduces the usable MTU of a tunnel. The “null@l2tp” method makes use of this for keepalive packets, so they are passed up to the fastd userspace when using the L2TP kernel offload feature.
Handshake format¶
The first 4 bytes (after the L2TP header if it exists, of the packet otherwise) form the handshake header:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x01 | 0x00 | TLV Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The rest of the handshake packet consists of TLV records, the total length of which is given by the TLV Length header field (in big-endian byte order).
Each of the following TLV records starts with a 2-byte type field, followed by a 2-byte length field and the arbitrary-length value. There is no special alignment defined for the TLV records. All integers that are part of the TLV format (in particular, the type and length fields) are encoded in little-endian byte order.
TLV record types¶
Record ID | Value description | Format | Values |
---|---|---|---|
0x0000 |
Handshake type | 1-byte unsigned integer | {1, 2, 3} |
0x0001 |
Reply code | 1-byte unsigned integer | {0 (success), 1 (mandatory record missing), 2 (unacceptable value)} |
0x0002 |
Error detail | 1/2-byte unsigned integer | Record type which caused an error |
0x0003 |
Flags | variable-length bit field | L2TP_SUPPORT=0x01 (sender supports L2TP control message headers) |
0x0004 |
Mode | 1-byte unsigned integer | {0 (TAP mode), 1 (TUN mode)} |
0x0005 |
Protocol name | variable-length string | “ec25519-fhmqvc” |
0x0006 |
Sender key | 32-byte public key | |
0x0007 |
Recipient key | 32-byte public key | |
0x0008 |
Sender handshake key | 32-byte public key | |
0x0009 |
Recipient handshake key | 32-byte public key | |
0x000a |
Authentication tag (obsolete) | 32-byte opaque value | Not used anymore |
0x000b |
MTU | 2-byte unsigned integer | |
0x000c |
Method name | variable-length string | |
0x000d |
Version name | variable-length string | |
0x000e |
Method list | zero-separated string list | |
0x000f |
TLV authentication tag | 32-byte opaque value |
Handshake protocol¶
The following specification describes the current handshake as it is performed by fastd versions since v11.
The handshake protocol consists of three packets. See also: ec25519, FHMQV-C
The following fields are sent in all three packets as different fastd versions expect them in different parts of the handshake:
- Mode (TUN/TAP)
- MTU
- fastd version (e.g.
v15
) - Protocol name (
ec25519-fhmqvc
)
Handshake request¶
The first packet of a handshake contains the following additional fields:
- Handshake type (0x01)
- FHMQV-C values:
- Sender key \(\hat{A}\)
- Recipient key \(\hat{B}\)
- Sender handshake key \(X\)
The recipient key may be omitted if the recipient identity is unknown because the handshake was triggered by an unexpected data packet.
Handshake reply¶
The second packet of a handshake contains the following additional fields:
- Handshake type (0x02)
- Reply code (0x00)
- Method list (list of all supported methods)
- FHMQV-C values:
- Sender key \(\hat{B}\)
- Recipient key \(\hat{A}\)
- Sender handshake key \(Y\)
- Recipient handshake key \(X\)
- TLV authentication tag \(\text{MAC}_B\)
Handshake finish¶
The second packet of a handshake contains the following additional fields:
- Handshake type (0x03)
- Reply code (0x00)
- Method (the chosen encryption/authentication scheme)
- FHMQV-C values:
- Sender key \(\hat{A}\)
- Recipient key \(\hat{B}\)
- Sender handshake key \(X\)
- Recipient handshake key \(Y\)
- TLV authentication tag \(\text{MAC}_A\)
Handshake error¶
When an unacceptable handshake is received, fastd will respond with an error packet. The error packet contains the following fields:
- Handshake type (the type of the packet that is answered plus 1)
- Reply code (0x01 when a record is missing from the handshake, 0x02 when a value is unacceptable)
- Error detail (the record type ID which caused the error)
Payload packets¶
The payload packet structure is defined by the methods; at the moment most methods use the same format, starting with a 24 byte header, followed by the actual payload:
- Byte 1: Packet type (
0x00
when both sides of a connection are fastd v22 or newer,0x02
otherwise) - Byte 2: Flags (method-specific; unused, always
0x00
) - Bytes 3-8: Packet sequence number/nonce (big endian; incremented by 2 for each packet; one side of a connection uses the even sequence numbers and the other side the odd ones)
- Bytes 9-24: Authentication tag (method-specific)
The “null” method uses only a 1-byte header: The packet type is directly followed by the payload data.
The “null@l2tp” method uses an 8-byte header, which is the same as the L2TPv3 Session Header over UDP, with no Cookie and no L2-Specific Sublayer (as specified in RFC3931). fastd always uses the L2TP Session ID 1.