mirror of
https://github.com/rosenpass/rosenpass.git
synced 2025-12-05 20:40:02 -08:00
feat(whitepaper): Introduce protocol extensions & specify WG integration as one
This commit is contained in:
Karolin Varner
BIN
papers/graphics/rosenpass-wireguard-hybrid-security.pdf
Normal file
BIN
papers/graphics/rosenpass-wireguard-hybrid-security.pdf
Normal file
Binary file not shown.
@@ -2,6 +2,7 @@
|
||||
\usepackage{amssymb}
|
||||
\usepackage{mathtools}
|
||||
\usepackage{fontspec}
|
||||
\usepackage{dirtytalk}
|
||||
|
||||
%font fallback
|
||||
\directlua{luaotfload.add_fallback
|
||||
|
||||
@@ -8,13 +8,15 @@ author:
|
||||
- Lisa Schmidt = {Scientific Illustrator – \\url{mullana.de}}
|
||||
- Prabhpreet Dua
|
||||
abstract: |
|
||||
Rosenpass is used to create post-quantum-secure VPNs. Rosenpass computes a shared key, WireGuard (WG) [@wg] uses the shared key to establish a secure connection. Rosenpass can also be used without WireGuard, deriving post-quantum-secure symmetric keys for another application. The Rosenpass protocol builds on “Post-quantum WireGuard” (PQWG) [@pqwg] and improves it by using a cookie mechanism to provide security against state disruption attacks.
|
||||
Rosenpass is a post-quantum-secure authenticated key exchange protocol. Its main practical use case is creating post-quantum-secure VPNs by combining WireGuard and Rosenpass.
|
||||
|
||||
The WireGuard implementation enjoys great trust from the cryptography community and has excellent performance characteristics. To preserve these features, the Rosenpass application runs side-by-side with WireGuard and supplies a new post-quantum-secure pre-shared key (PSK) every two minutes. WireGuard itself still performs the pre-quantum-secure key exchange and transfers any transport data with no involvement from Rosenpass at all.
|
||||
In this combination, Rosenpass generates a post-quantum-secure shared key every two minutes that is then used by WireGuard (WG) [@wg] to establish a secure connection. Rosenpass can also be used without WireGuard, providing post-quantum-secure symmetric keys for other applications, as long as the other application accepts a pre-shared key and provides cryptographic security based on the pre-shared key alone.
|
||||
|
||||
The Rosenpass protocol builds on “Post-quantum WireGuard” (PQWG) [@pqwg] and improves it by using a cookie mechanism to provide security against state disruption attacks. From a cryptographic perspective, Rosenpass can be thought of as a post-quantum secure variant of the Noise IK[@noise] key exchange. \say{Noise IK} means that the protocol makes both parties authenticate themselves, but that the initiator knows before the protocol starts which other party they are communicating with. There is no negotiation step where the responder communicates their identity to the initiator.
|
||||
|
||||
The Rosenpass project consists of a protocol description, an implementation written in Rust, and a symbolic analysis of the protocol’s security using ProVerif [@proverif]. We are working on a cryptographic security proof using CryptoVerif [@cryptoverif].
|
||||
|
||||
This document is a guide for engineers and researchers implementing the protocol; a scientific paper discussing the security properties of Rosenpass is work in progress.
|
||||
This document is a guide for engineers and researchers implementing the protocol.
|
||||
---
|
||||
|
||||
\enlargethispage{5mm}
|
||||
@@ -31,7 +33,7 @@ abstract: |
|
||||
|
||||
# Security
|
||||
|
||||
Rosenpass inherits most security properties from Post-Quantum WireGuard (PQWG). The security properties mentioned here are covered by the symbolic analysis in the Rosenpass repository.
|
||||
Rosenpass inherits most security properties from Post-Quantum WireGuard (PQWG). The security properties mentioned here are covered by the symbolic analysis in the Rosenpass repository.
|
||||
|
||||
## Secrecy
|
||||
Three key encapsulations using the keypairs `sski`/`spki`, `sskr`/`spkr`, and `eski`/`epki` provide secrecy (see Section \ref{variables} for an introduction of the variables). Their respective ciphertexts are called `scti`, `sctr`, and `ectr` and the resulting keys are called `spti`, `sptr`, `epti`. A single secure encapsulation is sufficient to provide secrecy. We use two different KEMs (Key Encapsulation Mechanisms; see Section \ref{skem}): Kyber and Classic McEliece.
|
||||
@@ -154,16 +156,18 @@ Rosenpass uses two types of ID variables. See Figure \ref{img:HashingTree} for h
|
||||
|
||||
The first lower-case character indicates whether the variable is a session ID (`sid`) or a peer ID (`pid`). The final character indicates the role using the characters `i`, `r`, `m`, or `t`, for `initiator`, `responder`, `mine`, or `theirs` respectively.
|
||||
|
||||
### Symmetric Keys
|
||||
|
||||
Rosenpass uses two symmetric key variables `psk` and `osk` in its interface, and maintains the entire handshake state in a variable called the chaining key.
|
||||
### Symmetric Keys {#symmetric-keys}
|
||||
|
||||
Rosenpass uses two main symmetric key variables `psk` and `osk` in its interface, and maintains the entire handshake state in a variable called the chaining key.
|
||||
|
||||
* `psk`: A pre-shared key that can be optionally supplied as input to Rosenpass.
|
||||
* `osk`: The output shared key, generated by Rosenpass and supplied to WireGuard for use as its pre-shared key.
|
||||
* `ck`: The chaining key.
|
||||
* `osk`: The output shared key, generated by Rosenpass. The main use case is to supply the key to WireGuard for use as its pre-shared key.
|
||||
* `ck`: The chaining key. This refers to various intermediate keys produced during the execution of the protocol, before the final `osk` is produced.
|
||||
|
||||
We mix all key material (e.g. `psk`) into the chaining key and derive symmetric keys such as `osk` from it. We authenticate public values by mixing them into the chaining key; in particular, we include the entire protocol transcript in the chaining key, i.e., all values transmitted over the network.
|
||||
|
||||
The protocol allows for multiple `osk`s to be generated; each of these keys is labeled with a domain separator to make sure different key usages are always given separate keys. The domain separator for using Rosenpass and WireGuard together is a token generated using the domain separator sequence `["rosenpass.eu", "wireguard psk"]` (see Fig. \ref{img:HashingTree}), as described in \ref{protocol-extension-wireguard-psk}. Third-parties using Rosenpass-keys for other purposes are asked to define their own protocol-extensions. Standard protocol extensions are described in \ref{protocol-extensions}.
|
||||
|
||||
We mix all key material (e.g. `psk`) into the chaining key, and derive symmetric keys such as `osk` from it. We authenticate public values by mixing them into the chaining key; in particular, we include the entire protocol transcript in the chaining key, i.e., all values transmitted over the network.
|
||||
|
||||
## Hashes
|
||||
|
||||
@@ -182,7 +186,7 @@ Using one hash function for multiple purposes can cause real-world security issu
|
||||
\setupimage{landscape,fullpage,label=img:HashingTree}
|
||||
|
||||
|
||||
Each tree node $\circ{}$ in Figure 3 represents the application of the keyed hash function, using the previous chaining key value as first parameter. The root of the tree is the zero key. In level one, the `PROTOCOL` identifier is applied to the zero key to generate a label unique across cryptographic protocols (unless the same label is deliberately used elsewhere). In level two, purpose identifiers are applied to the protocol label to generate labels to use with each separate hash function application within the Rosenpass protocol. The following layers contain the inputs used in each separate usage of the hash function: Beneath the identifiers `"mac"`, `"cookie"`, `"peer id"`, and `"biscuit additional data"` are hash functions or message authentication codes with a small number of inputs. The second, third, and fourth column in Figure 3 cover the long sequential branch beneath the identifier `"chaining key init"` representing the entire protocol execution, one column for each message processed during the handshake. The leaves beneath `"chaining key extract"` in the left column represent pseudo-random labels for use when extracting values from the chaining key during the protocol execution. These values such as `mix >` appear as outputs in the left column, and then as inputs `< mix` in the other three columns.
|
||||
Each tree node $\circ{}$ in Figure \ref{img:HashingTree} represents the application of the keyed hash function, using the previous chaining key value as first parameter. The root of the tree is the zero key. In level one, the `PROTOCOL` identifier is applied to the zero key to generate a label unique across cryptographic protocols (unless the same label is deliberately used elsewhere). In level two, purpose identifiers are applied to the protocol label to generate labels to use with each separate hash function application within the Rosenpass protocol. The following layers contain the inputs used in each separate usage of the hash function: Beneath the identifiers `"mac"`, `"cookie"`, `"peer id"`, and `"biscuit additional data"` are hash functions or message authentication codes with a small number of inputs. The second, third, and fourth column in Figure \ref{img:HashingTree} cover the long sequential branch beneath the identifier `"chaining key init"` representing the entire protocol execution, one column for each message processed during the handshake. The leaves beneath `"chaining key extract"` in the left column represent pseudo-random labels for use when extracting values from the chaining key during the protocol execution. These values such as `mix >` appear as outputs in the left column, and then as inputs `< mix` in the other three columns.
|
||||
|
||||
The protocol identifier depends on the hash function used with the respective peer is defined as follows if BLAKE2s [@rfc_blake2] is used:
|
||||
|
||||
@@ -289,7 +293,7 @@ fn lookup_session(sid);
|
||||
|
||||
The protocol framework used by Rosenpass allows arbitrarily many different keys to be extracted using labels for each key. The `extract_key` function is used to derive protocol-internal keys, its labels are under the “chaining key extract” node in Figure \ref{img:HashingTree}. The export key function is used to export application keys.
|
||||
|
||||
Third-party applications using the protocol are supposed to choose a unique label (e.g., their domain name) and use that as their own namespace for custom labels. The Rosenpass project itself uses the “rosenpass.eu” namespace.
|
||||
Third-party applications using the protocol are supposed to define a protocol extension (see \ref{protocol-extensions}) and choose a globally unique label, such as their domain name for custom labels of their own. The Rosenpass project itself uses the `["rosenpass.eu"]` namespace in the WireGuard PSK protocol extension (see \ref{protocol-extension-wireguard-psk}).
|
||||
|
||||
Applications can cache or statically compile the pseudo-random label values into their binary to improve performance.
|
||||
|
||||
@@ -421,6 +425,18 @@ fn enter_live() {
|
||||
txkr ← extract_key("responder payload encryption");
|
||||
txnm ← 0;
|
||||
txnt ← 0;
|
||||
|
||||
// Setup output keys for protocol extensions such as the
|
||||
// WireGuard PSK protocol extension.
|
||||
setup_osks();
|
||||
}
|
||||
```
|
||||
|
||||
The final step `setup_osks()` can be defined by protocol extensions (see \ref{protocol-extensions}) to set up `osk`s for custom use cases. By default, the WireGuard PSK (see \ref{protocol-extension-wireguard-psk}) is active.
|
||||
|
||||
```pseudorust
|
||||
fn setup_osks() {
|
||||
... // Defined by protocol extensions
|
||||
}
|
||||
```
|
||||
|
||||
@@ -448,11 +464,11 @@ ICR5 and ICR6 perform biscuit replay protection using the biscuit number. This i
|
||||
|
||||
### Denial of Service Mitigation and Cookies
|
||||
|
||||
Rosenpass derives its cookie-based DoS mitigation technique for a responder when receiving InitHello messages from Wireguard [@wg].
|
||||
Rosenpass derives its cookie-based DoS mitigation technique for a responder when receiving InitHello messages from Wireguard [@wg].
|
||||
|
||||
When the responder is under load, it may choose to not process further InitHello handshake messages, but instead to respond with a cookie reply message (see Figure \ref{img:MessageTypes}).
|
||||
|
||||
The sender of the exchange then uses this cookie in order to resend the message and have it accepted the following time by the reciever.
|
||||
The sender of the exchange then uses this cookie in order to resend the message and have it accepted the following time by the reciever.
|
||||
|
||||
For an initiator, Rosenpass ignores all messages when under load.
|
||||
|
||||
@@ -465,7 +481,7 @@ cookie_value = lhash("cookie-value", cookie_secret, initiator_host_info)[0..16]
|
||||
cookie_encrypted = XAEAD(lhash("cookie-key", spkm), nonce, cookie_value, mac_peer)
|
||||
```
|
||||
|
||||
where `cookie_secret` is a secret variable that changes every two minutes to a random value. Moreover, `lhash` is always instantiated with SHAKE256 when computing `cookie_value` for compatability reasons. `initiator_host_info` is used to identify the initiator host, and is implementation-specific for the client. This paramaters used to identify the host must be carefully chosen to ensure there is a unique mapping, especially when using IPv4 and IPv6 addresses to identify the host (such as taking care of IPv6 link-local addresses). `cookie_value` is a truncated 16 byte value from the above hash operation. `mac_peer` is the `mac` field of the peer's handshake message to which message is the reply.
|
||||
where `cookie_secret` is a secret variable that changes every two minutes to a random value. Moreover, `lhash` is always instantiated with SHAKE256 when computing `cookie_value` for compatability reasons. `initiator_host_info` is used to identify the initiator host, and is implementation-specific for the client. This paramaters used to identify the host must be carefully chosen to ensure there is a unique mapping, especially when using IPv4 and IPv6 addresses to identify the host (such as taking care of IPv6 link-local addresses). `cookie_value` is a truncated 16 byte value from the above hash operation. `mac_peer` is the `mac` field of the peer's handshake message to which message is the reply.
|
||||
|
||||
#### Envelope `mac` Field
|
||||
|
||||
@@ -495,13 +511,13 @@ else {
|
||||
Here, `seconds_since_update(peer.cookie_value)` is the amount of time in seconds ellapsed since last cookie was received, and `COOKIE_WIRE_DATA` are the message contents of all bytes of the retransmitted message prior to the `cookie` field.
|
||||
|
||||
The inititator can use an invalid value for the `cookie` value, when the responder is not under load, and the responder must ignore this value.
|
||||
However, when the responder is under load, it may reject InitHello messages with the invalid `cookie` value, and issue a cookie reply message.
|
||||
However, when the responder is under load, it may reject InitHello messages with the invalid `cookie` value, and issue a cookie reply message.
|
||||
|
||||
### Conditions to trigger DoS Mechanism
|
||||
|
||||
This whitepaper does not mandate any specific mechanism to detect responder contention (also mentioned as the under load condition) that would trigger use of the cookie mechanism.
|
||||
|
||||
For the reference implemenation, Rosenpass has derived inspiration from the Linux implementation of Wireguard. This implementation suggests that the reciever keep track of the number of messages it is processing at a given time.
|
||||
For the reference implemenation, Rosenpass has derived inspiration from the Linux implementation of Wireguard. This implementation suggests that the reciever keep track of the number of messages it is processing at a given time.
|
||||
|
||||
On receiving an incoming message, if the length of the message queue to be processed exceeds a threshold `MAX_QUEUED_INCOMING_HANDSHAKES_THRESHOLD`, the client is considered under load and its state is stored as under load. In addition, the timestamp of this instant when the client was last under load is stored. When recieving subsequent messages, if the client is still in an under load state, the client will check if the time ellpased since the client was last under load has exceeded `LAST_UNDER_LOAD_WINDOW` seconds. If this is the case, the client will update its state to normal operation, and process the message in a normal fashion.
|
||||
|
||||
@@ -520,18 +536,131 @@ The responder uses less complex form of the same mechanism: The responder never
|
||||
|
||||
### Interaction with cookie reply system
|
||||
|
||||
The cookie reply system does not interfere with the retransmission logic discussed above.
|
||||
The cookie reply system does not interfere with the retransmission logic discussed above.
|
||||
|
||||
When the initator is under load, it will ignore processing any incoming messages.
|
||||
|
||||
When a responder is under load and it receives an InitHello handshake message, the InitHello message will be discarded and a cookie reply message is sent. The initiator, then on the reciept of the cookie reply message, will store a decrypted `cookie_value` to set the `cookie` field to subsequently sent messages. As per the retransmission mechanism above, the initiator will send a retransmitted InitHello message with a valid `cookie` value appended. On receiving the retransmitted handshake message, the responder will validate the `cookie` value and resume with the handshake process.
|
||||
When a responder is under load and it receives an InitHello handshake message, the InitHello message will be discarded and a cookie reply message is sent. The initiator, then on the reciept of the cookie reply message, will store a decrypted `cookie_value` to set the `cookie` field to subsequently sent messages. As per the retransmission mechanism above, the initiator will send a retransmitted InitHello message with a valid `cookie` value appended. On receiving the retransmitted handshake message, the responder will validate the `cookie` value and resume with the handshake process.
|
||||
|
||||
When the responder is under load and it recieves an InitConf message, the message will be directly processed without checking the validity of the cookie field.
|
||||
|
||||
# Protocol extensions {#protocol-extensions}
|
||||
|
||||
The main extension point for the Rosenpass protocol is to generate `osk`s (speak output shared keys, see Sec. \ref{symmetric-keys}) for purposes other than using them to secure WireGuard. By default, the Rosenpass application generates keys for the WireGuard PSK (see \ref{protocol-extension-wireguard-psk}). It would not be impossible to use the keys generated for WireGuard in other use cases, but this might lead to attacks[@oraclecloning]. Specifying a custom protocol extension in practice just means settling on alternative domain separators (see Sec. \ref{symmetric-keys}, Fig. \ref{img:HashingTree}).
|
||||
|
||||
## Extension: WireGuard PSK {#protocol-extension-wireguard-psk}
|
||||
|
||||
The WireGuard PSK protocol extension is active by default; this is the mode where Rosenpass is used to provide post-quantum security for WireGuard. Hybrid security (i.e. redundant pre-quantum and post-quantum security) is achieved because WireGuard provides pre-quantum security, with or without Rosenpass.
|
||||
|
||||
This extension uses the `"rosenpass.eu"` namespace for user-labels and specifies a single additional user-label:
|
||||
|
||||
* `["rosenpass.eu", "wireguard psk"]`
|
||||
|
||||
The label's full domain separator is
|
||||
|
||||
* `[PROTOCOL, "user", "rosenpass.eu", "wireguard psk"]`
|
||||
|
||||
and can be seen in Figure \ref{img:HashingTree}.
|
||||
|
||||
We require two extra per-peer configuration variables:
|
||||
|
||||
* `wireguard_interface` — Name of a local network interface. Identifies local WireGuard interface we are supplying a PSK to.
|
||||
* `wireguard_peer` — A WireGuard public key. Identifies the particular WireGuard peer whose connection we are supplying PSKs for.
|
||||
|
||||
When creating the WireGuard interface for use with Rosenpass, the PSK used by WireGuard must be initialized to a random value; otherwise, WireGuard can establish an insecure key before Rosenpass had a change to exchange its own key.
|
||||
|
||||
```pseudorust
|
||||
fn on_wireguard_setup() {
|
||||
// We use a random PSK to make sure the other side will never
|
||||
// have a matching PSK when the WireGuard interface is created.
|
||||
//
|
||||
// Never use a fixed value here as this would lead to an attack!
|
||||
let fake_wireguard_psk = random_key();
|
||||
|
||||
// How the interface is create
|
||||
let wg_peer = WireGuard::setup_peer()
|
||||
.public_key(wireguard_peer)
|
||||
... // Supply any custom peerconfiguration
|
||||
.psk(fake_wireguard_psk);
|
||||
|
||||
// The random PSK must be supplied before the
|
||||
// WireGuard interface comes up
|
||||
WireGuard::setup_interface()
|
||||
.name(wireguard_interface)
|
||||
... // Supply any custom configuration
|
||||
.add_peer(wg_peer)
|
||||
.create();
|
||||
}
|
||||
```
|
||||
|
||||
Every time a key is successfully negotiated, we upload the key to WireGuard.
|
||||
For this protocol extension, the `setup_osks()` function is thus defined as:
|
||||
|
||||
```pseudorust
|
||||
fn setup_osks() {
|
||||
// Generate WireGuard OSK (output shared key) from Rosenpass'
|
||||
// perspective, respectively the PSK (preshared key) from
|
||||
// WireGuard's perspective
|
||||
let wireguard_psk = export_key("rosenpass.eu", "wireguard psk");
|
||||
|
||||
/// Supply the PSK to WireGuard
|
||||
WireGuard::get_interface(wireguard_interface)
|
||||
.get_peer(wireguard_peer)
|
||||
.set_psk(wireguard_psk);
|
||||
}
|
||||
```
|
||||
|
||||
The Rosenpass protocol uses key renegotiation, just like WireGuard.
|
||||
If no new `osk` is produced within a set amount of time, the OSK generated by Rosenpass times out.
|
||||
In this case, the WireGuard PSK must be overwritten with a random key.
|
||||
This interaction is visualized in Figure \ref{img:ExtWireguardPSKHybridSecurity}.
|
||||
|
||||
```pseudorust
|
||||
fn on_key_timeout() {
|
||||
// Generate a random – deliberately invalid – WireGuard PSK.
|
||||
// Never use a fixed value here as this would lead to an attack!
|
||||
let fake_wireguard_psk = random_key();
|
||||
|
||||
// Securely erase the PSK currently used by WireGuard by
|
||||
// overwriting it with the fake key we just generated.
|
||||
WireGuard::get_interface(wireguard_interface)
|
||||
.get_peer(wireguard_peer)
|
||||
.set_psk(fake_wireguard_psk);
|
||||
}
|
||||
```
|
||||
|
||||
\setupimage{label=img:ExtWireguardPSKHybridSecurity,fullpage}
|
||||
|
||||
|
||||
# Changelog
|
||||
|
||||
### 0.3.x
|
||||
|
||||
#### 2025-06-24 – Specifying the `osk` used for WireGuard as a protocol extension
|
||||
|
||||
\vspace{0.5em}
|
||||
|
||||
Author: Karolin varner
|
||||
|
||||
PR: [#664](https://github.com/rosenpass/rosenpass/pull/664)
|
||||
|
||||
\vspace{0.5em}
|
||||
|
||||
We introduce the concept of protocol extensions to make the option of using Rosenpass for purposes other than encrypting WireGuard more explicit. This captures the status-quo in a better way and does not constitute a functional change of the protocol.
|
||||
|
||||
When we designed the Rosenpass protocol, we built it with support for alternative `osk`-labels in mind.
|
||||
This is why we specified the domain separator for the `osk` to be `[PROTOCOL, "user", "rosenpass.eu", "wireguard psk"]`.
|
||||
By choosing alternative values for the namespace (e.g. `"myorg.eu"` instead of `"rosenpass.eu`) and the label (e.g. `"MyApp Symmetric Encryption"`), the protocol could easily accommodate alternative usage scenarios.
|
||||
|
||||
By introducing the concept of protocol extensions, we make this possibility explicit.
|
||||
|
||||
1. Reworded the abstract to make it clearer that Rosenpass can be used for other purposes than to secure WireGuard
|
||||
2. Reworded Section Symmetric Keys, adding references to the new section on protocol extension
|
||||
3. Added a `setup_osks()` function in section Hashes, to make the reference to protocol extensions explicit
|
||||
4. Added a new section on protocol extensions and the standard extension for using Rosenpass with WireGuard
|
||||
5. Added a new graphic to showcase how Rosenpass and WireGuard interact
|
||||
5. Minor formatting and intra-document references fixes
|
||||
|
||||
#### 2025-05-22 - SHAKE256 keyed hash
|
||||
\vspace{0.5em}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user