diff --git a/protocols/BHP.md b/protocols/BHP.md index 3f6a0d6dd923cdf83c54883f66947198a26be2a6..3a0823679f52e5934c4fec5c3cce4b95aa0debf6 100644 --- a/protocols/BHP.md +++ b/protocols/BHP.md @@ -6,13 +6,13 @@ Bramble Handshake Protocol (BHP) is a key agreement protocol for delay-tolerant BHP is designed to be used with Bramble Transport Protocol (BTP) in handshake mode. The shared secret produced by BHP can be used to derive a root key for upgrading BTP to transport mode, which provides forward secrecy. -BHP can operate over any connection-oriented, bidirectional transport protocol. Unidirectional transports are not suitable. +BHP can operate over any connection-oriented, bidirectional transport protocol. ### 1.1 Adversary Model We assume the adversary can observe, block, delay, replay and modify traffic on all underlying transports. -We do not assume the peers exchanged their long-term public keys over a secure channel. If the adversary intercepted the prior exchange of long-term public keys and replaced them with its own public keys then BHP does not detect or prevent man-in-the-middle attacks. If the adversary knows both peers' long-term public keys but did not replace them during the prior exchange then BHP prevents man-in-the-middle attacks. +We do not assume that the peers exchanged their long-term public keys over a secure channel. If the adversary intercepted the prior exchange of long-term public keys and replaced them with its own public keys then BHP does not detect or prevent man-in-the-middle attacks. If the adversary knows both peers' long-term public keys but did not replace them during the prior exchange then BHP prevents man-in-the-middle attacks. BHP does not rely on lower protocol layers to provide confidentiality, integrity, authenticity or forward secrecy. If the traffic between peers needs to be indistinguishable from random then BHP should be used with a protocol that provides concealability, such as BTP. @@ -20,9 +20,9 @@ BHP does not rely on lower protocol layers to provide confidentiality, integrity Before two peers can communicate using BHP they must exchange long-term public keys. BHP does not specify how this should be done. Any synchronous or asynchronous communication channel can be used, subject to the caveat that if an adversary can replace the keys being exchanged then the adversary can carry out a man-in-the-middle attack against BHP. -The peers must also establish a connection over a bidirectional transport. Each peer needs to know which peer it's connected to so it can use the appropriate long-term public key for authenticating the other peer. When BHP is used with BTP in handshake mode, BTP enables the peers to identify each other so they can look up the appropriate long-term public keys. +The peers must also establish a connection over a bidirectional transport. Each peer needs to know which peer it's connected to so it can use the appropriate long-term public key for authenticating the other peer. When BHP is used with BTP in handshake mode, BTP enables the peers to identify each other so they can look up the appropriate long-term public keys. If BHP is used without BTP then some other means must be used to determine which long-term public key to use for authenticating the peer. -Each peer uses the long-term public keys to decide whether it will take the role of **Alice** or **Bob** in BHP. The peers take roles according to the lexicographic order of their long-term public keys, compared as byte strings. The peer with the earlier key plays the role of Alice, while the peer with the later key plays the role of Bob. The roles are symmetrical except for the order of the protocol steps. +The peers take the roles of **Alice** and **Bob** according to the lexicographic order of their long-term public keys, compared as byte strings. The peer with the earlier key plays the role of Alice, while the peer with the later key plays the role of Bob. The roles are symmetrical except for the order of the protocol steps. ### 1.3 Notation diff --git a/protocols/BRP.md b/protocols/BRP.md index 62311e157bab0e6381a9e07a1739112b6d6aeb83..ba6407bc2e6c8cbd7f94e3b20dbf2d16f630c3f2 100644 --- a/protocols/BRP.md +++ b/protocols/BRP.md @@ -2,29 +2,29 @@ ## 1 Introduction -Bramble Rendezvous Protocol (BRP) is a discovery protocol for peer-to-peer networks. It enables two peers that have previously exchanged public keys to connect to each other. No other information, such as network addresses, needs to be exchanged in advance. +Bramble Rendezvous Protocol (BRP) is a discovery protocol for peer-to-peer networks. It enables two peers that have previously exchanged public keys to connect to each other. No other information, such as network addresses, needs to be exchanged in advance. Instead the peers use a shared secret derived from their public keys to generate pseudo-random contact details for connecting to each other over various transports. BRP also produces a shared key that can be used by other protocols for securing communication between the peers. -BRP is designed to operate over a connection-oriented, bidirectional transport protocol. Unidirectional transports are not suitable. - -The current version of BRP uses the Tor hidden service protocol as its transport. Future versions of BRP may support other transports. +BRP is designed to operate over connection-oriented, bidirectional transport protocols. The current version of BRP uses the Tor hidden service protocol as its transport. Future versions of BRP may support other transports. ### 1.1 Motivation -BRP enables two peers in a peer-to-peer network to connect to each other. In general terms this requires each peer to have some kind of network address at which the other peer can contact it. +BRP enables two peers in a peer-to-peer network to connect to each other by exchanging public keys. The public keys can be encoded as short text strings that can be exchanged over a wide range of channels, such as email or social networks. -If the peers were to exchange network addresses over an insecure channel, an adversary who saw the addresses could connect to them in order to track when the peers were online or carry out attacks such as flooding the peers with connection attempts. +The peers' contact details are derived from the shared secret, rather than being encodied in the same strings as the public keys. This has the following advantages: -To avoid exposing their network addresses, peers in BRP exchange public keys instead of network addresses. Two peers that have exchanged public keys can derive a shared secret that is not known to any other party, including an adversary who has seen both public keys. The peers then derive network addresses from the shared secret and use these addresses for connecting to each other. +* The amount of information that needs to be exchanged is small +* The information is stable over time, so it can be exchanged asynchronously +* Contact details that might be used to identify or track the peers are not exposed to the channel where the exchange takes place ### 1.2 Adversary Model We assume the adversary can read, modify, delete and insert traffic on all transports at will. -We do not assume the peers exchanged their public keys over a secure channel. If the adversary intercepted the prior exchange of public keys and replaced them with its own public keys then BRP does not detect or prevent man-in-the-middle attacks. +We do not assume that the peers exchanged their public keys over a secure channel. If the adversary intercepted the prior exchange of public keys and replaced them with its own public keys then BRP does not detect or prevent man-in-the-middle attacks. -If the adversary knows both peers' public keys but did not replace them during the prior exchange then BRP prevents the adversary from knowing the peers' network addresses, unless the adversary can see the addresses by observing the underlying transport. +If the adversary knows both peers' public keys but did not replace them during the prior exchange then BRP prevents the adversary from learning the peers' network addresses, unless the adversary can see the addresses by observing the underlying transport. -BRP does not exchange any data over the underlying transport; it just establishes connections. As such, it does not rely on lower protocol layers to provide confidentiality, integrity, authenticity, forward secrecy or concealability. +BRP does not rely on lower protocol layers to provide confidentiality, integrity, authenticity, forward secrecy or concealability. ### 1.3 Notation @@ -64,7 +64,7 @@ All hashes are HASH\_LEN bytes, all symmetric keys are KEY\_LEN bytes, and the o Before two peers can communicate using BRP they must exchange public keys. BRP does not specify how this should be done. Any synchronous or asynchronous communication channel can be used, subject to the caveat that if an adversary can modify the keys being exchanged then the adversary can carry out a man-in-the-middle attack against BRP. -After exchanging public keys, each peer decides whether it will take the role of **Alice** or **Bob** in BRP. The peers take roles according to the lexicographic order of their public keys, compared as byte strings. The peer with the earlier key plays the role of Alice, while the peer with the later key plays the role of Bob. The roles are symmetrical. +The peers take the roles of **Alice** and **Bob** in BRP according to the lexicographic order of their public keys, compared as byte strings. The peer with the earlier key plays the role of Alice, while the peer with the later key plays the role of Bob. The roles are symmetrical. ## 2 The Rendezvous Protocol @@ -91,11 +91,11 @@ The protocol version is 0 for the current version of BRP. ### 2.2 Creating Network Endpoints -Each peer uses the rendezvous key to create a **network endpoint** for each transport the peer supports. The peer derives a **stream key** for each transport from the rendezvous key. The peer uses the stream key to generate pseudo-random network addresses for its own endpoint and the other peer's endpoint. The other peer derives the same stream key and generates the same addresses, so the peers know the addresses of each other's endpoints. +Each peer uses the rendezvous key to create a **network endpoint** for each transport the peer supports. The peer derives a **stream key** for each transport from the rendezvous key. The peer uses the stream key to generate pseudo-random **contact details** for its own endpoint and the other peer's endpoint. The other peer derives the same stream key and generates the same contact details, so the peers know each other's contact details. - stream\_key = KDF(rendezvous\_key, "org.briarproject.bramble.rendezvous/KEY\_MATERIAL", transport\_id) -The only transport used by this version of BRP is the Tor hidden service protocol, which has the transport identifier "org.briarproject.bramble.tor". +The only transport used by the current version of BRP is the Tor hidden service protocol, which has the transport identifier "org.briarproject.bramble.tor". #### 2.2.1 Network Endpoints for the Tor Hidden Service Protocol @@ -119,6 +119,8 @@ If no connection is made within 48 hours of the initial key exchange, the rendez The application layer is responsible for deciding how to use any rendezvous connections created by BRP. BRP does not authenticate the remote peer, but it makes the static master key available to the application layer so that other protocols can derive keys from it, for example to encrypt and authenticate communication with the remote peer over a rendezvous connection. +Once the peers have established a secure connection they may exchange long-term contact details to replace the temporary contact details created by BRP. + ## 3 Man-in-the-Middle Attacks -As noted above, if an adversary intercepted the prior exchange of public keys and replaced them with its own public keys then BRP does not prevent man-in-the-middle attacks. Each peer will derive a static master key and network addresses that are known to the adversary rather than the other peer, allowing the adversary to interpose itself between the peers. The adversary will have access to any future communication between the peers that is secured with keys derived from the static master key. +As noted above, if an adversary intercepted the prior exchange of public keys and replaced them with its own public keys then BRP does not prevent man-in-the-middle attacks. Each peer will derive a static master key and contact details that are known to the adversary rather than the other peer, allowing the adversary to interpose itself between the peers. The adversary will have access to any future communication between the peers that is secured with keys derived from the static master key.