Add fastdp-crypto docs

2017-02-10 14:49:47 +00:00
1 parent f592e4b70a
commit 86f716c38c
@@ -10,8 +10,9 @@ properties:
 * Data confidentiality.
 * Data origin authentication.
 * Integrity.
-* Anti-replay service.
-* Limited traffic flow confidentiality.
+* Anti-replay.
+* Limited traffic flow confidentiality as fast datapath VXLAN packets are fully
+  encrypted.

 ## Notation

@@ -52,9 +52,9 @@ overlay, which has a more sophisticated dynamic mechanism for coping
 with low path MTUs.

 To avoid triggering this fallback in typical deployments, the datapath
-interface is statically configured with an MTU of 1410 bytes allowing
+interface is statically configured with an MTU of 1376 bytes allowing
 it to work with most underlay network provider MTUs, including GCE at
-1460 bytes (the fifty byte difference accommodates the vxlan overhead).
+1460 bytes (the eighty four byte difference accommodates the encrypted vxlan overhead).
 This value can be overridden by setting `WEAVE_MTU` at launch if
 necessary.

@@ -74,9 +74,7 @@ For more information on this command, see [Using Fast Datapath](/site/using-weav

 **Q: Does encryption work with fastdp?**

-Encryption does not work with fast datapath. If you enable encryption using the `--password` option to launch Weave (or you use the `WEAVE_PASSWORD` environment variable), fast datapath will by default be disabled. 
-
-You can however have a mixture of fast datapath connections over trusted links, as well as, encrypted connections over untrusted links.
+Yes, 1.9 version of Weave Net added the encryption feature to fastdp.

 See [Using Fast Datapath](/site/using-weave/fastdp.md) for more information.

@@ -85,7 +83,7 @@ See [Using Fast Datapath](/site/using-weave/fastdp.md) for more information.
 Yes, of course!  Weave allows you to run isolated networks and still allow open communications between individual containers from those isolated networks. You can find information on how to do this in [Application Isolation](/site/using-weave/application-isolation.md).


-**Q: Which ports does Weave Net use (e.g. if I am configuring a firewall) ?**
+**<a name=ports></a>Q: Which ports does Weave Net use (e.g. if I am configuring a firewall) ?**

 You must permit traffic to flow through TCP 6783 and UDP 6783/6784,
 which are Weave’s control and data ports.
@@ -98,6 +96,11 @@ The Weave Net daemon listens on localhost (127.0.0.1) TCP port 6784
 for commands from other Weave Net components. This port should not be
 opened to other hosts.

+When using encrypted fast datapath, make sure that underlying
+network does not block ESP traffic (IP protocol 50). For instance
+on Google Cloud Platform a firewall rule for allowing ESP traffic has
+to be installed.
+
 **<a name=own-image></a>Q: Why do you use your own Docker image `weaveworks/ubuntu`?**

 The official Ubuntu image does not contain the `ping` and `nc`
@@ -52,10 +52,6 @@ Weave Net automatically chooses the fastest available method to
 transport data between peers. The best performing of these 
 (the 'fast datapath') offers near-native throughput and latency.

-Fast datapath does not support encryption. For full details on configuring
-Weave when you have connections that traverse untrusted networks,
-see [Securing Connections Across Untrusted Networks](/site/using-weave/security-untrusted-networks.md) for more details.
-
 See [Using Fast Datapath](/site/using-weave/fastdp.md) and
 [How Fast Datapath Works](/site/how-it-works/fastdp-how-it-works.md).

@@ -177,7 +173,8 @@ mechanism which you can use in conjunction with or as an
 alternative to any other security technologies you have 
 running alongside Weave. 

-Weave Net implements encryption and security using the Go version of [Daniel J. Bernstein's NaCl library](http://nacl.cr.yp.to/index.html).
+Weave Net implements encryption and security using the Go version of [Daniel J.  Bernstein's NaCl library](http://nacl.cr.yp.to/index.html),
+and, additionally in the case of encrypted fast datapath using [the cryptography framework of the Linux kernel](https://en.wikipedia.org/wiki/Crypto_API_(Linux)).

 For information on how to secure your Docker network connections, see [Securing Connections Across Untrusted Networks](/site/using-weave/security-untrusted-networks.md) and for a more technical discussion on how Weave implements encryption see, [Weave Encryption](/site/how-it-works/encryption.md) and [How Weave Implements Encryption](/site/how-it-works/encryption-implementation.md).

@@ -107,6 +107,8 @@ attacks.

 ####<a name="udp"></a>Encrypting and Decrypting UDP Packets

+#####Sleeve
+
 UDP connections carry captured traffic between peers. For a UDP packet
 sent between peers that are using crypto, the encapsulation looks as
 follows:
@@ -179,7 +181,33 @@ 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.

+#####Fast Datapath
+
+Encryption in fastdp uses [the ESP protocol of IPsec](https://tools.ietf.org/html/rfc2406)
+in the transport mode. Each VXLAN packet is encrypted with
+[AES in GCM mode](https://tools.ietf.org/html/rfc4106aesgcm), with 32 byte key and
+4 byte salt. This combo provides the following security properties:
+
+* Data confidentiality.
+* Data origin authentication.
+* Integrity.
+* Anti-replay.
+* Limited traffic flow confidentiality as VXLAN packets are fully encrypted.
+
+For each connection direction, a different AES-GCM key and salt is used.
+The pairs are derived with [HKDF](https://tools.ietf.org/html/rfc5869)
+to which we pass a randomly generated 32 byte salt transferred over the encrypted
+control plane channel between peers.
+
+To prevent from replay attacks, which are possible because of the size of
+sequence number field in ESP (4 bytes), we use extended sequence numbers
+implemented by [ESN](https://tools.ietf.org/html/rfc4304).
+
+Authentication of ESP packet integrity and origin is ensured by 16 byte
+Integrity Check Value of AES-GCM.
+
 **See Also**

 * [architecture documentation](https://github.com/weaveworks/weave/blob/master/docs/architecture.txt)
+ * [fastdp encryption](https://github.com/weaveworks/weave/blob/master/docs/fastdp-crypto.md)
 * [Securing Containers Across Untrusted Networks](/site/using-weave/security-untrusted-networks.md)
@@ -9,7 +9,8 @@ Weave Net peers
 communication
 [can be encrypted](/site/using-weave/security-untrusted-networks.md).

-Encryption is accomplished using the [NaCl](http://nacl.cr.yp.to/)
+Encryption of control plane traffic (TCP) and data plane traffic (UDP) of sleeve
+overlay is accomplished using the [NaCl](http://nacl.cr.yp.to/)
 crypto libraries, employing Curve25519, XSalsa20 and Poly1305 to
 encrypt and authenticate messages. Weave Net protects against
 injection and replay attacks for traffic forwarded between peers.
@@ -32,6 +33,11 @@ extensions to TLS such as [DTLS](https://tools.ietf.org/html/rfc4347)
 which can operate over UDP, these are not widely implemented and
 deployed.

+In the case of fast datapath, data plane traffic is encrypted by using
+[ESP of IPsec](https://tools.ietf.org/html/rfc2406).
+The process of encryption is handled by the Linux kernel and is controlled via
+the IP transformation framework (XFRM).
+
 **See Also**

 * [How Weave Implements Encryption](/site/how-it-works/encryption-implementation.md)
@@ -58,6 +58,9 @@ A [special no-overlay mode for EC2](/site/using-weave/awsvpc.md) can
 optionally be enabled, which allows containers to communicate at the
 full speed of the underlying network.

+To make encryption in fast datapath work on Google Cloud Platform, see
+[here](/site/faq.md#ports).
+
 **See Also** 

 * [Using Weave Net](/site/using-weave.md)
@@ -42,7 +42,7 @@ See [How Fast Datapath Works](/site/using-weave/fastdp.md) for more information.

 Weave uses industry-standard VXLAN encapsulation between hosts. This means you can continue using your favorite packet analyzing tools, such as ‘Wireshark’ to inspect and troubleshoot protocols.

-###Weave Net is Secure With Built-in Encryption
+###Weave Net is Secure

 Weave Net traverses firewalls without requiring a TCP add-on. You can encrypt your traffic, which allows you to connect to apps on hosts even across an untrusted network.  

@@ -151,7 +151,7 @@ The list of variables you can set is:
 * WEAVE\_EXPOSE\_IP - set the IP address used as a gateway from the
  Weave network to the host network - this is useful if you are
  configuring the addon as a static pod.
-* WEAVE\_MTU - Weave Net defaults to 1410 bytes, but you can set a
+* WEAVE\_MTU - Weave Net defaults to 1376 bytes, but you can set a
  smaller size if your underlying network has a tighter limit, or set
  a larger size for better performance if your network supports jumbo
  frames - see [here](/site/using-weave/fastdp.md#mtu) for more
@@ -89,7 +89,7 @@ your cluster.

 The Maximum Transmission Unit, or MTU, is the technical term for the
 limit on how big a single packet can be on the network. Weave Net
-defaults to 1410 bytes. This default works across almost all networks, but for better 
+defaults to 1376 bytes. This default works across almost all networks, but for better 
 performance you can set it to a larger MTU size. 

 The AWS network supports packets of up to 9000 bytes.  
@@ -18,9 +18,15 @@ You can disable fastdp by enabling the `WEAVE_NO_FASTDP` environment variable at

 ###Fast Datapath and Encryption

-Encryption does not work with fast datapath. If you enable encryption using the `--password` option to launch weave (or you use the `WEAVE_PASSWORD` environment variable), fast datapath will by default be disabled. 
+Fast datapath implements encryption using IPsec which is configured with IP
+transformation framework (XFRM) provided by the Linux kernel.

-When encryption is not in use there may be other conditions in which the fast datapath reverts to `sleeve mode`. Once these conditions pass, Weave Net reverts back to using fastdp. To view which mode Weave Net is using, run `weave status connections`.
+Each encrypted dataplane packet is encapsulated into [ESP](https://tools.ietf.org/html/rfc2406),
+thus in some networks a firewall rule for allowing ESP traffic needs to be installed. E.g. Google
+Cloud Platform denies ESP packets by default.
+
+See [How Weave Implements Encryption](/site/how-it-works/encryption-implementation.md)
+for more details for the fastdp encryption.

 ###Viewing Connection Mode Fastdp or Sleeve

@@ -46,12 +52,13 @@ Where fastdp indicates that fast datapath is being used on a connection. If fast

 The Maximum Transmission Unit, or MTU, is the technical term for the
 limit on how big a single packet can be on the network. Weave Net
-defaults to 1410 bytes, but you can set a smaller size if your
+defaults to 1376 bytes, but you can set a smaller size if your
 underlying network has a tighter limit, or set a larger size for
 better performance.

 The underlying network must be able to deliver packets of the size
-specified plus overheads of around 50 bytes, or else Weave Net will
+specified plus overheads of around 84-87 bytes (the final MTU should be
+divisible by four), or else Weave Net will
 fall back to Sleeve for that connection.  This requirement applies
 to _every path_ between peers. 

@@ -59,7 +66,7 @@ To specify a different MTU, before launching Weave Net set the
 environment variable `WEAVE_MTU`.  For example, for a typical "jumbo
 frame" configuration:

-    $ WEAVE_MTU=8950 weave launch host2 host3
+    $ WEAVE_MTU=8916 weave launch host2 host3

 **See Also**

@@ -41,8 +41,8 @@ the `--trusted-subnets` argument with `weave launch`:

 If *both* peers at the end of a connection consider the other to be in
 a trusted subnet, Weave Net attempts to establish fast datapath
-connectivity, which is unencrypted. Otherwise the slower `sleeve` mode
-is used and communication is encrypted.
+connectivity, which is unencrypted. Otherwise communication is encrypted which
+imposes overheads.

 Configured trusted subnets are shown in [`weave status`](/site/troubleshooting.md#weave-status).