Merge PR snabbco#47 (concurrent SAs per route) into master

src/program/vita/README

@@ -25,9 +25,9 @@ also requires a CPU that support AES-NI and AVX-2. It is also required to boot
 Linux with the kernel parameter iommu=off for Snabb device drivers to function.
 
 Vita will fork into five processes which individually handle key management,
-outbound routing, inbound routing, encapsulation, and decapsulation. The
-resulting processes can be bound to specific CPUs using the “--cpu” option in
-the given order.
+routing on the private port, routing on the public port, encapsulation, and
+decapsulation. The resulting processes can be bound to specific CPU cores using
+the “--cpu” option.
 
 Example:
   vita --name my-vita --cpus 0,1,2,3,4

src/program/vita/README.exchange

@@ -1,4 +1,4 @@
-VITA: SIMPLE KEY EXCHANGE (vita-ske, version 1g)
+VITA: SIMPLE KEY EXCHANGE (vita-ske, version 1i)
 
  A simple key negotiation protocol based on pre-shared symmetric keys that
  provides authentication, perfect forward secrecy, and is immune to replay
@@ -23,35 +23,36 @@ Notational Conventions:
 
 Description:
 
- Let k be a pre-shared symmetric key. Let spi be a “Security Parameter Index”
+ Let k be a pre-shared symmetric key. Let r be a “Security Parameter Index”
  (SPI). Let n1 and n2 be random 256‑bit nonces, where n1 is chosen by us.
 
   ← n1
   → n2
 
  Let (p1, s1) and (p2, s2) be random, ephemeral, asymmetric key pairs, where
- (p1, s1) is choosen by us. Let h1 = HMAC(k, spi ‖ n1 ‖ n2 ‖ p1).
+ (p1, s1) is choosen by us. Let spi1 and spi2 be child SPIs, where spi1 is
+ choosen by us. Let h1 = HMAC(k, r ‖ n1 ‖ n2 ‖ spi1 ‖ p1).
 
-  ← p1 ‖ h1
-  → p2 ‖ h2
+  ← spi1 ‖ p1 ‖ h1
+  → spi2 ‖ p2 ‖ h2
 
- Ensure that h2 = HMAC(k, spi ‖ n2 ‖ n1 ‖ p2). Let q = DH(s1, p2), and ensure
- that p2 is a valid argument. Let rx = HASH(q ‖ p1 ‖ p2) and
- tx = HASH(q ‖ p2 ‖ p1) be key material. Assign (spi, rx) to the incoming
- “Security Association” (SA), and (spi, tx) to the outgoing SA.
+ Ensure that h2 = HMAC(k, r ‖ n2 ‖ n1 ‖ spi2 ‖ p2). Let q = DH(s1, p2), and
+ ensure that p2 is a valid argument. Let rx = HASH(q ‖ p1 ‖ p2) and
+ tx = HASH(q ‖ p2 ‖ p1) be key material. Assign (spi1, rx) to the inbound
+ “Security Association” (SA), and (spi2, tx) to the outbound SA.
 
  The description above illustrates the perspective of an active party adhering
  to the protocol, i.e. the exchange is initiated by us. An opposite, passive
  party adhering to the protocol, i.e. one that is merely responding to a key
  exchange initiated by an active party, must ensure that the tuple
- (spi, p2, h2) was received and authenticated before computing and sending its
- response tuple (spi, p1, h1). For a passive party the order of messages during
- the exchange is reversed:
+ (spi2, p2, h2) was received and authenticated before computing and sending its
+ response tuple (spi1, p1, h1). For a passive party the order of messages
+ during the exchange is reversed:
 
   → n2
   ← n1
-  → p2 ‖ h2        (ensure h2 is verified before we reply)
-  ← p1 ‖ h1
+  → spi2 ‖ p2 ‖ h2        (ensure h2 is verified before we reply)
+  ← spi1 ‖ p1 ‖ h1
 
  Note that there might be no passive party in an exchange if both parties have
  initiated the exchange before receiving an initial nonce message.
@@ -60,8 +61,8 @@ Security Proof:
 
  Assuming an attacker can not guess k, and n1 has enough entropy so that the
  probability that the tuple (n1, p2) has occurred before is negligible, they
- are unable to produce the value h2 = HMAC(k, spi ‖ n2 ‖ n1 ‖ p2), and thus are
- unable to complete a key exchange.
+ are unable to produce the value h2 = HMAC(k, r ‖ n2 ‖ n1 ‖ spi2 ‖ p2), and
+ thus are unable to complete a key exchange.
 
  Assuming an attacker can not guess s1 or s2, they are unable to produce
  q = DH(s1, p2) or q = DH(s2, p1), and subsequently derive rx or tx, and thus
@@ -73,6 +74,9 @@ Security Proof:
 
 Notes:
 
+ • The outputs of this protocol are choosen specifically to support the AES-GCM
+   algorithm with 128‑bit keys as used in an IPsec ESP data plane.
+
  • Future versions of this protocol may introduce the use of a key derivation
    function (KDF), such as libsodium’s crypto_kdf_blake2b_derive_from_key, to
    derive additional key material from rx or tx.
@@ -81,9 +85,15 @@ References:
 
  • The spiped protocol:
    https://github.com/Tarsnap/spiped/blob/d1e62a8/DESIGN.md#spiped-design
+
  • Additional discussion of the spiped protocol:
    https://github.com/Tarsnap/spiped/issues/151
+
  • The Sodium crypto library (libsodium):
    https://download.libsodium.org/doc/
+
  • Security Architecture for the Internet Protocol:
    https://tools.ietf.org/html/rfc4301
+
+ • The use of AES-GCM in IPsec ESP:
+   https://tools.ietf.org/html/rfc4106