reorganization-edit docs for WP
This commit is contained in:
1 parent
532a6b69d9
commit
bdc9eae000
59 files changed
+3184
-2148
No files matched your search
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Encryption and Weave Net
|
||||
layout: default
|
||||
---
|
||||
|
||||
|
||||
|
||||
Weave can be configured to encrypt both the data passing over the TCP
|
||||
connections and the payloads of UDP packets sent between peers. This
|
||||
is accomplished using the [NaCl](http://nacl.cr.yp.to/) crypto
|
||||
libraries, employing Curve25519, XSalsa20 and Poly1305 to encrypt and
|
||||
authenticate messages. Weave protects against injection and replay
|
||||
attacks for traffic forwarded between peers.
|
||||
|
||||
NaCl was selected because of its good reputation both in terms of
|
||||
selection and implementation of ciphers, but equally importantly, its
|
||||
clear APIs, good documentation and high-quality
|
||||
[go implementation](https://godoc.org/golang.org/x/crypto/nacl). It is
|
||||
quite difficult to use NaCl incorrectly. Contrast this with libraries
|
||||
such as OpenSSL where the library and its APIs are vast in size,
|
||||
poorly documented, and easily used wrongly.
|
||||
|
||||
There are some similarities between Weave's crypto and
|
||||
[TLS](https://tools.ietf.org/html/rfc4346). Weave does not need to cater
|
||||
for multiple cipher suites, certificate exchange and other
|
||||
requirements emanating from X509, and a number of other features. This
|
||||
simplifies the protocol and implementation considerably. On the other
|
||||
hand, Weave needs to support UDP transports, and while there are
|
||||
extensions to TLS such as [DTLS](https://tools.ietf.org/html/rfc4347)
|
||||
which can operate over UDP, these are not widely implemented and
|
||||
deployed.
|
||||
|
||||
**See Also**
|
||||
|
||||
* [How Weave Implements Encryption](/site/encryption/ephemeral-key.md)
|
||||
* [Securing Containers Across Untrusted Networks](/site/using-weave/security-untrusted-networks.md)
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
title: How Weave Implements Encryption
|
||||
layout: default
|
||||
---
|
||||
|
||||
This section discusses the folloiwng topics:
|
||||
|
||||
* [Establishing the Ephemeral Session Key](#ephemeral-key)
|
||||
* [Key Generation](#csprng)
|
||||
* [Encypting and Decrypting TCP Messages](#tcp)
|
||||
* [Encypting and Decrypting UDP Messages](#udp)
|
||||
* [Further Reading](#plugin)
|
||||
|
||||
|
||||
|
||||
####<a name="ephemeral-key"></a>Establishing the Ephemeral Session Key
|
||||
|
||||
For every connection between peers, a fresh public/private key pair is
|
||||
created at both ends, using NaCl's `GenerateKey` function. The public
|
||||
key portion is sent to the other end as part of the initial handshake
|
||||
performed over TCP. Peers that were started with a password do not
|
||||
continue with connection establishment unless they receive a public
|
||||
key from the remote peer. Thus either all peers in a weave network
|
||||
must be supplied with a password, or none.
|
||||
|
||||
When a peer has received a public key from the remote peer, it uses
|
||||
this to form the ephemeral session key for this connection. The public
|
||||
key from the remote peer is combined with the private key for the
|
||||
local peer in the usual [Diffie-Hellman way](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange),
|
||||
resulting in both peersarriving at the same shared key. To this is appended the supplied
|
||||
password, and the result is hashed through SHA256, to form the final
|
||||
ephemeral session key.
|
||||
|
||||
The supplied password is never exchanged directly, and is thoroughly
|
||||
mixed into the shared secret. Furthermore, the rate at which TCP connections
|
||||
are accepted is limited by Weave to 10Hz, which thwarts online
|
||||
dictionary attacks on reasonably strong passwords.
|
||||
|
||||
The shared key formed by Diffie-Hellman is 256 bits long. Appending
|
||||
the password to this obviously makes it longer by an unknown amount,
|
||||
and the use of SHA256 reduces this back to 256 bits, to form the final
|
||||
ephemeral session key. This late combination with the password
|
||||
eliminates any "Man In The Middle" attacks: sniffing the public key
|
||||
exchange between the two peers and faking their responses will not
|
||||
grant an attacker knowledge of the password, and therefor, an attacker would
|
||||
not be able to form valid ephemeral session keys.
|
||||
|
||||
The same ephemeral session key is used for both TCP and UDP traffic
|
||||
between two peers.
|
||||
|
||||
###<a name="csprng"></a> Key Generation and The Linux CSPRNG
|
||||
|
||||
Generating fresh keys for every connection
|
||||
provides forward secrecy at the cost of placing a demand on the Linux
|
||||
CSPRNG (accessed by `GenerateKey` via `/dev/urandom`) proportional to
|
||||
the number of inbound connection attempts. Weave has accept throttling
|
||||
to mitigate against denial of service attacks that seek to deplete the
|
||||
CSPRNG entropy pool, however even at the lower bound of ten requests
|
||||
per second, there may not be enough entropy gathered on a headless
|
||||
system to keep pace.
|
||||
|
||||
Under such conditions, the consequences will be limited to slowing
|
||||
down processes reading from the blocking `/dev/random` device as the
|
||||
kernel waits for enough new entropy to be harvested. It is important
|
||||
to note that contrary to intuition, this low entropy state does not
|
||||
compromise the ongoing use of `/dev/urandom`. [Expert
|
||||
opinion](http://blog.cr.yp.to/20140205-entropy.html)
|
||||
asserts that as long as the CSPRNG is seeded with enough entropy (for example,
|
||||
256 bits) before random number generation commences, then the output is
|
||||
entirely safe for use as key material.
|
||||
|
||||
By way of comparison, this is exactly how OpenSSL works - it reads 256
|
||||
bits of entropy at startup, and uses that to seed an internal CSPRNG,
|
||||
which is used to generate keys. While Weave could have taken
|
||||
the same approach and built a custom CSPRNG to work around the
|
||||
potential `/dev/random` blocking issue, the decision was made to rely
|
||||
on the [heavily scrutinised](http://eprint.iacr.org/2012/251.pdf) Linux random number
|
||||
generator as [advised
|
||||
here](http://cr.yp.to/highspeed/coolnacl-20120725.pdf) (page 10,
|
||||
'Centralizing randomness').
|
||||
|
||||
>>**Note:**The aforementioned notwithstanding, if
|
||||
Weave's demand on `/dev/urandom` is causing you problems with blocking
|
||||
`/dev/random` reads, please get in touch with us - we'd love to hear
|
||||
about your use case.
|
||||
|
||||
####<a name="tcp"></a>Encypting and Decrypting TCP Messages
|
||||
|
||||
TCP connection are only used to exchange topology information between
|
||||
peers, via a message-based protocol. Encryption of each message is
|
||||
carried out by NaCl's `secretbox.Seal` function using the ephemeral
|
||||
session key and a nonce. The nonce contains the message sequence
|
||||
number, which is incremented for every message sent, and a bit
|
||||
indicating the polarity of the connection at the sender ('1' for
|
||||
outbound). The latter is required by the
|
||||
[NaCl Security Model](http://nacl.cr.yp.to/box.html) in order to
|
||||
ensure that the two ends of the connection do not use the same nonces.
|
||||
|
||||
Decryption of a message at the receiver is carried out by NaCl's
|
||||
`secretbox.Open` function using the ephemeral session key and a
|
||||
nonce. The receiver maintains its own message sequence number, which
|
||||
it increments for every message it decrypted successfully. The nonce
|
||||
is constructed from that sequence number and the connection
|
||||
polarity. As a result the receiver will only be able to decrypt a
|
||||
message if it has the expected sequence number. This prevents replay
|
||||
attacks.
|
||||
|
||||
####<a name="udp"></a>Encrypting and Decrypting UDP Packets
|
||||
|
||||
UDP connections carry captured traffic between peers. For a UDP packet
|
||||
sent between peers that are using crypto, the encapsulation looks as
|
||||
follows:
|
||||
|
||||
+-----------------------------------+
|
||||
| Name of sending peer |
|
||||
+-----------------------------------+
|
||||
| Message Sequence No and flags |
|
||||
+-----------------------------------+
|
||||
| NaCl SecretBox overheads |
|
||||
+-----------------------------------+ -+
|
||||
| Frame 1: Name of capturing peer | |
|
||||
+-----------------------------------+ | This section is encrypted
|
||||
| Frame 1: Name of destination peer | | using the ephemeral session
|
||||
+-----------------------------------+ | key between the weave peers
|
||||
| Frame 1: Captured payload length | | sending and receiving this
|
||||
+-----------------------------------+ | packet.
|
||||
| Frame 1: Captured payload | |
|
||||
+-----------------------------------+ |
|
||||
| Frame 2: Name of capturing peer | |
|
||||
+-----------------------------------+ |
|
||||
| Frame 2: Name of destination peer | |
|
||||
+-----------------------------------+ |
|
||||
| Frame 2: Captured payload length | |
|
||||
+-----------------------------------+ |
|
||||
| Frame 2: Captured payload | |
|
||||
+-----------------------------------+ |
|
||||
| ... | |
|
||||
+-----------------------------------+ |
|
||||
| Frame N: Name of capturing peer | |
|
||||
+-----------------------------------+ |
|
||||
| Frame N: Name of destination peer | |
|
||||
+-----------------------------------+ |
|
||||
| Frame N: Captured payload length | |
|
||||
+-----------------------------------+ |
|
||||
| Frame N: Captured payload | |
|
||||
+-----------------------------------+ -+
|
||||
|
||||
This is very similar to the [non-crypto encapsulation](/site/router-topology/router-encapsulation.md).
|
||||
|
||||
All of the frames on a connection are encrypted with the same
|
||||
ephemeral session key, and a nonce constructed from a message sequence
|
||||
number, flags and the connection polarity. This is very similar to the
|
||||
TCP encryption scheme, and encryption is again done with the NaCl
|
||||
`secretbox.Seal` function. The main difference is that the message
|
||||
sequence number and flags are transmitted as part of the message,
|
||||
unencrypted.
|
||||
|
||||
The receiver uses the name of the sending peer to determine which
|
||||
ephemeral session key and local cryptographic state to use for
|
||||
decryption. Frames which are to be forwarded on to some further peer
|
||||
will be re-encrypted with the relevant ephemeral session keys for the
|
||||
onward connections. Thus all traffic is fully decrypted on every peer
|
||||
it passes through.
|
||||
|
||||
Decryption is once again carried out by NaCl's `secretbox.Open`
|
||||
function using the ephemeral session key and nonce. The latter is
|
||||
constructed from the message sequence number and flags that appeared
|
||||
in the unencrypted portion of the received message, and the connection
|
||||
polarity.
|
||||
|
||||
To guard against replay attacks, the receiver maintains some state in
|
||||
which it remembers the highest message sequence number seen. It could
|
||||
simply reject messages with lower sequence numbers, but that could
|
||||
result in excessive message loss when messages are re-ordered. The
|
||||
receiver therefore additionally maintains a set of received message
|
||||
sequence numbers in a window below the highest number seen, and only
|
||||
rejects messages with a sequence number below that window, or
|
||||
contained in the set. The window spans at least 2^20 message sequence
|
||||
numbers, and hence any re-ordering between the most recent ~1 million
|
||||
messages is handled without dropping messages.
|
||||
|
||||
**See Also**
|
||||
|
||||
* [architecture documentation](https://github.com/weaveworks/weave/blob/master/docs/architecture.txt)
|
||||
* [Securing Containers Across Untrusted Networks](/site/using-weave/security-untrusted-networks.md)
|
||||
Reference in new issue
Block a user