diff --git a/openvpn-wire-protocol.xml b/openvpn-wire-protocol.xml
index 8a63fe9..cbbd79b 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,
+ AEAD, and CBC/OFB/CTR
+ packet format.
@@ -1531,6 +1532,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
@@ -1541,6 +1543,137 @@ 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 to 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 encryption 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 epoch counter before moving to a new epoch. 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.
+
+
+
+ Example calculation:
+
+ Using limits documents and p=2^-57 and L=2**14:
+
+ q <= (p^(1/2) * 2^(129/2) - 1) / (L + 1)>
+
+ gives use basically limit that TLS uses:
+ q <= 24^(24.9999)
+
+
+ When using L = 2^12 (packet/buffer size of 1500 rounded up to the nearest power of 2)
+ we get:
+
+ q <= 2^(26.999)
+
+
+
+ The following table gives an overview of the limits for AES-GCM invocations when calculating them with above formula
+
+
+ packet size
+
+ Maximum number of packets
+ 1500
+ 28.4
+
+ 1600
+ 28.35
+
+ 2048
+ 2^28
+
+ 4096
+ 2^27
+
+ 9000
+ 2^25.8
+
+ 16384
+ 2^25
+
+ 65336
+ 2^23
+
+
+ Implementations 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. E.g. the current OpenVPN
+ implementation will always try to send up to the internal buffer size of 1600 byte in the default
+ configuration.
+
+
+
+ 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 again specified differently
+ for DTLS 1.3 and the data usage limit document. For OpenVPN we set the number to 2^36 for all
+ ciphers, the same DTLS 1.3. An implementation may chose 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 HDKF-Expand-Label in TLS 1.3.
+
+ For OpenVPN the epoch 0 key E0 is the OpenVPN key, for any further key, the key derivation is
+ E_N+1 = HKDF-Expand-Label(E_N, "OpenVPN data key update", "", 256)
+
+
+ The per epoch data channel key is derived via
+ K_i = HKDF-Expand-Label(E_i, "OpenVPN epoch key", "", 256)
+
+
+ The epoch K_i will then be used for the actual data encryption, the keys is are first
+ bytes from key_c2s and key_s2c respectively. And the implicit_iv is formed from the
+ first 96 bit (12 bytes) from auth_c2s and auth_s2c respectively.
+
+
+
+
+ On the sending will encrypt packet until the limit for the epoch K_i is reach. At this point,
+ the sender will switch to the next epoch key.
+
+
+ Each peer is expected to hold the current epoch key K_i, the previous K_i and the a number of
+ future keys K_i+1, K_i+2,....,K_j+n. The number of future 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.
+
+
+ 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. OpenVPN chooses this approach over
+ the alternative that epochs are managed separately for both peers, to simplify key and also to
+ allow the receiver to trigger using a new encryption key.
+
+
+
+
The purpose of this feature is to allow a client to float between various client
@@ -1628,7 +1761,8 @@ struct datakeys {
- AEAD format with tag at the start:
+ This specificies the first version of AEAD data format that OpenVPN implements.
+ It has the AEAD tag at the start.
@@ -1636,7 +1770,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;
}
@@ -1644,28 +1778,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.
@@ -1697,9 +1813,78 @@ 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 contactination
+
Support of multiple key generations (epochs)
+
+
+ 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 48bit of counter for
+ that epoch. Each epoch uses a different a encryption/decryption key and a different
+ implicit_iv.
+
+
+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. Implementation are encouraged to a have a per epoch replay protection.
+ Using the whole packet_id as flat 64bit counter for replay protection will work as well
+ but will reject reordered packets from the older epoch when a (valid) packet
+ the epoch changes
+
+
+
+ The 96bit IV is constructed by using the 96 bit of implicit IV belonging to the epoch
+ and doing an XOR with the 48 bit epoch_counter.
+ IV = epoch_counter XOR implicit_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_v2 = 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).
@@ -2047,7 +2232,9 @@ INFO,EXTRA
-
+
+
+ A provable-security treatment of the key-wrap problem
@@ -2056,6 +2243,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;
@@ -2071,8 +2326,24 @@ INFO,EXTRA
&RFC5705;
-
+
&RFC8452;
+
+
+
+
+
+ Limits on Authenticated Encryption Use in TLS
+
+
+
+
+
+
+
+
+
+