diff --git a/openvpn-wire-protocol.xml b/openvpn-wire-protocol.xml
index 0a821d0..6f9cb21 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.
@@ -1462,7 +1463,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 that uses AEAD tag at the end
+ has a 64bit packet counters to allow for epoch ciphers.
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 +1534,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 +1545,207 @@ 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 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 for confidentialy limit:
+
+ 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 ≤ 24^(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
+
+
+ Instead of (implicitly) only tracking only the number of packets, an implementation can also instead
+ track the number of plain text blocks s and the number of packets q:
+
+
+ q + s ≤ p^(1/2) * 2^(129/2) - 1
+
+ Using our confidentially margin of 2^-57, this gives us:
+
+
+ q + s ≤ 2^36
+
+
+ Tracking the number of blocks of encrypted clear text data limit this allows not having to fix L or
+ in VPN terms, the maximum packet size. If VPN traffic is very mixed, e.g. a lot of small packets
+ that do not use the full MTU, this also allows more traffic to be encrypted before a rekey is
+ necessary.
+
+
+ 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 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.
+
+ For OpenVPN the epoch 1 key E_1 are the first 32 the OpenVPN data key. Note that unlike when
+ when using the OpenVPN key directly for encrypting/decryption, E_1 is the same for both direction
+ and basically only the first 32 bytes of key_c2s are used.
+
+
+ Note that 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, "epoch key", "", 256)
+
+ The epoch K_i will then be used for the actual data encryption. The encryption key for
+ the AEAD cipher are first bytes from key_c2s and key_s2c respectively. The number of bytes
+ depends on the key size of the cipher. And the implicit_iv is formed from the
+ first 96 bits (12 bytes) from auth_c2s and auth_s2c respectively.
+
+
+ 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;
+
+
+ Keep in mind that the " characters, like in TLS 1.3 are part of the label prefix.
+
+
+
+ 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 reach. 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 key 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 packet 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.
+
+
+
+
The purpose of this feature is to allow a client to float between various client
@@ -1629,7 +1833,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 +1842,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 +1850,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 +1885,80 @@ 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 48bit of counter for
+ that epoch. Each epoch uses a different a encryption/decryption key and a
+ different implicit_iv. The epoch select 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. Implementation 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 epoch when a (valid) packet if
+ the epoch changes as then there is a large gap in the counter that will not allow
+ any reordered packet.
+
+
+
+ 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 = 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 +2265,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 +2331,9 @@ INFO,EXTRA
-
+
+
+ A provable-security treatment of the key-wrap problem
@@ -2083,6 +2342,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 +2425,24 @@ INFO,EXTRA
&RFC5705;
-
+
&RFC8452;
+
+
+
+
+
+ Limits on Authenticated Encryption Use in TLS
+
+
+
+
+
+
+
+
+
+