diff --git a/openvpn-wire-protocol.xml b/openvpn-wire-protocol.xml
index 0a821d0..a03031e 100644
--- a/openvpn-wire-protocol.xml
+++ b/openvpn-wire-protocol.xml
@@ -1,4 +1,4 @@
-
+
for Peer-ID.
- For details about this opcode see sections about AEAD
- and CBC/OFB/CTR packet format.
+ For details about this opcode see the sections AEAD,
+ and CBC/OFB/CTR packet format.
@@ -1462,7 +1462,8 @@ struct key_exchange {
bit 7: The client is capable of sending exit notification via control channel using EXIT message. The client is accpting the protocol-flags pushed option for the EKM capability
bit 8: The client is capable of accepting AUTH_FAILED,TEMP messages.
bit 9: The client is capable of dynamic tls-crypt
-
bit 10: The client is capable of AEAD tag at the end of a data channel packet and capable of using 64bit packet counters for AEAD ciphers.
+
bit 10: The client is capable of using the epoch data format. This format uses the AEAD tag at the end and
+ has a 48 bit packet counters together with a 16 bit key-id that form a 64-bit packet id.
bit 11: The client is capable of parsing and receiving the dns messages pushed option.
bit 12: The client is capable of receiving PUSH_UPDATE message.
@@ -1532,6 +1533,7 @@ struct datakeys {
key_c2s and auth_c2s are used to encrypt/authenticate data from client to server
and key_s2c and auth_s2c are used to encrypt/authenticate from server to client.
+ Server and client in this context is TLS server and TLS client of the connection.
This key structure is normally generated by using RFC 5705 key material exporter
@@ -1542,6 +1544,230 @@ struct datakeys {
PRF.
+
+
+
+ Recent advances in cryptography research have shown that GCM ciphers, most notably AES-GCM have
+ theoretical vulnerabilities when AES-GCM is used with the same key with too many block encryption
+ invocations. See Usage Limits on AEAD Algorithms and the
+ referenced research papers in that document like for more information.
+
+
+ To avoid using the same encryption key for too many packets without requiring to do a full renegotiation
+ OpenVPN uses epoch data channel keys. The term epoch is used to avoid confusion with the already
+ existing term key-id and since DTLS 1.3 uses the same terminology.
+
+
+ A sender should calculate a safe amount of packets to send/number of encryptions that can be done.
+ The actual number depends on the cipher being used. From current
+ standards, there is no limit to consider for Chacha20-Poly1305, so a sender can use the full
+ 48 bit of the epoch counter for encrypting packets before moving to a new epoch and encryption key.
+ For AES-GCM, the limit is 2^32.5 when using a packet size of 1500 using this document and the safety
+ margin of 2^-50 but the TLS 1.3 standard uses a higher safety margin of 2^-57,
+ which translates to 2^24.5 for maximum TLS record sizes (2^14 or 16kB). OpenVPN implementations should
+ choose the same (higher) safety margin as TLS.
+
+
+ In order to guarantee that safety marging an implementation has to ensure that the number of plain text
+ blocks s and the number of packets q satisfies the following equation:
+
+
+ q + s ≤ p^(1/2) * 2^(129/2) - 1
+
+ Using our confidentially margin of 2^-57, this gives us:
+
+
+ q + s ≤ 2^36
+
+
+ When an implementation tracks the number of blocks of encrypted clear text and number of cipher invocation data (which is
+ identical to number of sent packets), this formula can be used to determine if the limit has been reached.
+
+
+ Alternatively, when not tracking the number of packets, an upper limit per encryption can be set. This limit is called L and is
+ set in number of blocks. E.g. in VPN terms, the maximum packet size divided by the block size, which is 16 bytes.
+ If VPN traffic is very mixed, e.g. a lot of small packets that do not use the full MTU, this will allow less traffic to be
+ encrypted before a rekey is necessary.
+
+
+ Implementations that use the simpler approach of only counting the number of packets before switching to a new epoch,
+ have to ensure to calculate the limit with the actual maximum size that they are willing to send a packet with and
+ not only with the current MTU size and use L accordingly in the calcualations. E.g. the current OpenVPN implementation
+ will always try to send up to the internal buffer size of 1600 byte in the default configuration.
+
+
+
+ Example calculations for confidentialy limit. This is done do to give an example for an implementation that
+ assumes a fixed L and to give an estimate how many packets can be encrypted assuming assuming a fixed packet
+ size.
+
+ Using the limits in the documents and p=2^-57 and L=2**10.
+
+ q ≤ (p^(1/2) * 2^(129/2) - 1) / (L + 1)>
+
+ gives us basically the same limit that TLS imposes:
+ q ≤ 2^(24.9999)
+
+
+ When using L = 2^7 (packet/buffer size of 1500 rounded up to the nearest power of 2 an)
+ we get:
+
+ q ≤ 2^(26.999)
+
+
+
+ For the integrity limit
+ v ≤ min(2^64, (p * 2^127) / (L + 1))
+
+
+ with p=2^-57, and setting v=3^36, we can have L to be up to 2^34
+ (256 GB). So for packet sizes used in the OpenVPN protocol
+ we ignore this formula as we are always within the safe limits.
+
+
+ The following table gives an overview of the limits for number of packets when calculating them with above confidentially formula.
+
+
+ packet size
+ Maximum number of packets
+ 64
+ 2^33
+
+ 1500
+ 2^29.4
+
+ 1600
+ 2^29.3
+
+ 2048
+ 2^29
+
+ 4096
+ 2^28
+
+ 9000
+ 2^26.8
+
+ 16384
+ 2^26
+
+ 65336
+ 2^24
+
+
+
+ The receiver should count the number of packets that have been received but failed verification.
+ The number of packets that fail verification and we can tolerate is specified differently
+ for DTLS 1.3 and the data usage limit document. For OpenVPN we set the number to the limit of
+ 2^36 packets failed verifications, the same as (D)TLS 1.3, which is lower than the theoretical limit.
+ An implementation may choose a lower number.
+
+
+
+
+ The epoch key generation is inspired by the TLS key generation and
+ HMAC-based Key Derivation Function (HKDF)
+ and the definition of HKDF-Expand-Label in TLS 1.3.
+
+
+
+ OpenVPN uses different epoch keys for the client to server and the server to client direction.
+ The epoch 1 key E_1 are the first 32 bytes of the OpenVPN key's key_c2s and key_s2c respectively.
+ Note, these keys serve the same purpose as the TLS 1.3 client_/server_application_traffic_secret_N
+ keys.
+
+
+ We start at epoch 1 instead epoch 0 for the key. This is done to allow for easier
+ implementation for the C-based OpenVPN implementation.
+
+
+ For any further key, the key derivation is
+ E_N+1 = OVPN-Expand-Label(E_N, "datakey upd", "", 32)
+
+
+ The per epoch data channel key is derived via
+ K_i = OVPN-Expand-Label(E_i, "data_key", "", key_size)
+ implicit_iv = OVPN-Expand-Label(E_i, "data_iv", "", implicit_iv_len)
+
+
+ The key K_i will then be used for the actual data encryption. The key_size parameter depends on the key size
+ of the encryption cipher being used. The parameter implicit_iv_len also depends on the IV length of the cipher
+ but for both AES-GCM and Chacha20-Poly1305, this is 12 bytes (96 bits).
+
+
+ The function OVPN-Expand-Label is identical to the HKDF-Expand-Label function of TLS 1.3 but uses
+ "ovpn " instead of "tls13 " as the label prefix. The hash function for OVPN-Expand-Label is SHA-256.
+
+
+OVPN-Expand-Label(Secret, Label, Context, Length) =
+ HKDF-Expand(Secret, OvpnLabel, Length)
+
+Where OvpnLabel is specified as:
+
+struct {
+ uint16 length = Length;
+ opaque label<6..255> = "ovpn " + Label;
+ opaque context<0..255> = Context;
+} OvpnLabel;
+
+
+
+
+
+ The key size of 4096 bit or 256 byte is used here to make these epoch data channel keys the same
+ format as the regular data channel keys.
+
+
+
+
+ When sending packets, a peer will encrypt packet until the limit for the epoch K_i is reached. At this point,
+ the sender will switch to the next epoch key K_i+1. The state for the sending side, only needs to keep
+ the current E_i key and the current encryption key K_i.
+
+
+ Each peer is expected to hold the current epoch key K_i, the previous K_i-1 and a number of
+ future keys K_i+1, K_i+2,....,K_i+j. The number of future keys j depends on the expected possible
+ data rate of the implementation and needs to be large enough that even when a reasonable amount of
+ packets is lost, the implementation will still be able to authenticate the packets.
+
+
+
+ Allowing multiple epochs keys requires the receiving side to keep multiple keys to able to decrypt and
+ verify packets with different epochs. An attacker can send a packet with a epoch that is a lot higher than
+ the current epoch. In order to avoid needing to the generate/keep arbitrary epoch decryption keys, the window
+ of future decryption keys that is acceptable should be limited. At the same time, the window needs to be large
+ enough that a long packet loss that causes all packets to be dropped (e.g. a topology change) does not
+ cause legitimate packets to be dropped.
+
+
+ For example, if we consider an implementation that allows to encrypt at data rate of 100 GBit/s and
+ to be able to deal with 60s of lost data, we have to calculate how many epochs the peer can use and
+ exhaust in this time. Assuming a small packet size of 128 byte, this gives us about 78 million packets
+ per second or about 2^26.2 packets per second. For the full minute we get 2^32.1 packets. Assuming
+ the limit of 2^28.3 packets per epoch for AES-GCM, we need 14 epoch keys to safely encrypt this
+ amount of data. A reasonable amount of future epoch data channel keys in this scenario could be
+ considered 16 or 32 keys.
+
+
+ When receiving an authenticated packet with a higher epoch than the currently used one, the
+ receiver of this packet SHOULD also switch to the same epoch. This allow also the receiver to
+ trigger using a new encryption key if in the future it becomes necessary. But this is optional
+ and an implementation can continue using the old send key as log as it is safe.
+
+
+ As addition a peer cannot regard apparent overuse of a send key by other the other peer as error as the
+ limit can change if new information is available but the peer MAY move to a higher sending key epoch of its
+ own to try to trigger the same on the peer as outlined in the previous paragraph.
+
+
+ This requirement of keeping only one past key but multiple future keys for an implementation is a trade-off.
+ Not being able to decrypt packets from an earlier epoch will result in packet loss while not being to decrypt
+ a legitimate packet from a future epoch, will result in the receiver never switching to the new epoch of the
+ sender and complete loss of the connectivity for that connection. Implementations can opt to also keep multiple
+ previous epoch keys if they don't want to make this trade-off.
+
+
+
The purpose of this feature is to allow a client to float between various client
@@ -1629,7 +1855,8 @@ struct datakeys {
- AEAD format with tag at the start:
+ This specifies the first version of AEAD data format that OpenVPN implements.
+ It has the AEAD tag at the start.
@@ -1637,7 +1864,7 @@ struct aead_packet {
int opcode:5;
int key_id:3;
int peer_id:24;
- uint32_t/uint_64_t packet_id;
+ uint32_t packet_id;
uint8_t[16] authentication_tag;
uint8_t* encrypted_payload;
}
@@ -1645,28 +1872,10 @@ struct aead_packet {
-
- AEAD format with tag at the end:
-
-
-
-struct aead_packet {
- int opcode:5;
- int key_id:3;
- int peer_id:24;
- uint32_t/uint64_t packet_id;
- uint8_t* encrypted_payload;
- uint8_t[16] authentication_tag;
-}
-
-
-
The packet_id together with the implicit IV forms the IV for
decryption. The packet_id is also used for the replay protection.
-
- When 64 bit packet ids are enabled, the size becomes 64 bit.
@@ -1698,9 +1907,83 @@ authenticated_data_v2 = opcode| key_id | peer_id | packet_id | payload
- The tag size is always 128 bit (16 bytes). (Same size as in TLS). If the
- protocol flag for AEAD tag at the end is in effect, the AEAD tag is at the end
- of the packet rather than at the start.
+ The tag size is always 128 bit (16 bytes). (Same size as in TLS).
+
+
+
+
+ This is the modern version of the AEAD data format in OpenVPN. The differences to the older
+ format are:
+
+
AEAD tag at the end of the packet
+
64 bit packet id
+
IV constructed with XOR instead of concatenation
+
Support of multiple key generations (epochs)
+
Only defined for DATA_V2 packets
+
+
+ The packet format with 64bit counter looks like this:
+
+
+struct aead_packet {
+ int opcode:5;
+ int key_id:3;
+ int peer_id:24;
+ uint_64_t packet_id;
+ uint8_t* encrypted_payload;
+ uint8_t[16] authentication_tag;
+}
+
+
+
+
+
+ The packet id is split into 16 bit bits of epoch and 48-bit of counter for
+ that epoch. Each epoch uses a different a encryption/decryption key and a
+ different implicit_iv. The epoch selects the key to use for decryption.
+
+
+struct packet_id {
+ uint epoch:16;
+ uint epoch_counter:48;
+}
+
+
+
+
+
+ The epoch_counter of the packet_id together with the implicit IV for the epoch
+ forms the IV for decryption. The epoch_counter is also used for the replay
+ protection. Implementations are encouraged to a have a per epoch replay protection.
+ Using the whole packet_id as a flat 64bit counter for replay protection will work as
+ well but will reject reordered packets from the older epochs. A (valid) packet
+ of the new the epoch will be seen as a large gap in the counter that and that will disallow any
+ allow any packet from an earlier epoch.
+
+
+
+ The 96bit IV is constructed by using the 96 bit of implicit IV belonging to the epoch
+ and doing an XOR with the 64 bit packet id of both epoch and epoch_counter.
+ IV = (epoch | epoch_counter) XOR implicit_iv_epoch
+
+
+ Note that this IV calculation assumes a big endian representation of the IV. I.e. the 8 bytes
+ on the wire of the epoch counter are XOR with the first 8 bytes of the implicitv_iv_epoch counter and the remaing 4 byte
+ are directly derived from the implict_iv_epoch.
+
+
+ This data format is only defined for DATA_V2 packets and therefore
+ the authenticated data includes opcode, key_id and peer_id.
+
+
+
+
+authenticated_data = opcode| key_id | peer_id | packet_id | payload
+
+
+
+
+ The tag size is always 128 bit (16 bytes) appended to the end of encrypted data (Same size as in TLS).
@@ -2007,8 +2290,7 @@ INFO,EXTRA
tls-ekm The OpenVPN key for the
data channel enryption should be derived using TLS key material exporter
dyn-tls-crypt Renegotion control channel use dynamic TLS crypt
-
aead-tag-end The AEAD tag is at the end of the data channel packets
-
pkt-id-64-bit Use 64 bit packet counter for AEAD data channel ciphers
+
aead-epoch Epoch keys and the data format are used
@@ -2074,7 +2356,9 @@ INFO,EXTRA
-
+
+
+ A provable-security treatment of the key-wrap problem
@@ -2083,6 +2367,74 @@ INFO,EXTRA
Sp 800-38d. recommendation for block cipher modes of operation: Galois/counter mode (gcm) and gmac
+
+
+
+ The Transport Layer Security (TLS) Protocol Version 1.3
+
+
+
+ This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery.
+ This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961. This document also specifies new requirements for TLS 1.2 implementations.
+
+
+
+
+
+
+
+
+
+ The Datagram Transport Layer Security (DTLS) Protocol Version 1.3
+
+
+
+
+
+ This document specifies version 1.3 of the Datagram Transport Layer Security (DTLS) protocol. DTLS 1.3 allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery.
+ The DTLS 1.3 protocol is based on the Transport Layer Security (TLS) 1.3 protocol and provides equivalent security guarantees with the exception of order protection / non-replayability. Datagram semantics of the underlying transport are preserved by the DTLS protocol.
+ This document obsoletes RFC 6347.
+
+
+
+
+
+
+
+Usage Limits on AEAD Algorithms
+
+ETH Zurich
+
+
+Mozilla
+
+
+Cloudflare
+
+
+
+An Authenticated Encryption with Associated Data (AEAD) algorithm provides confidentiality and integrity. Excessive use of the same key can give an attacker advantages in breaking these properties. This document provides simple guidance for users of common AEAD functions about how to limit the use of keys in order to bound the advantage given to an attacker.
+
+
+
+
+
+
+
+
+ HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
+
+
+
+
+ This document specifies a simple Hashed Message Authentication Code (HMAC)-based key derivation function (HKDF), which can be used as a building block in various protocols and applications. The key derivation function (KDF) is intended to support a wide range of applications and requirements, and is conservative in its use of cryptographic hash functions. This document is not an Internet Standards Track specification; it is published for informational purposes.
+
+
+
+
+
+
+
&RFC2104;
@@ -2098,8 +2450,24 @@ INFO,EXTRA
&RFC5705;
-
+
&RFC8452;
+
+
+
+
+
+ Limits on Authenticated Encryption Use in TLS
+
+
+
+
+
+
+
+
+
+