Add AES-256-GCM support to SPTPS.

[tinc] / doc / SPTPS

diff --git a/doc/SPTPS b/doc/SPTPS
index 78927f6..2da2760 100644 (file)
--- a/doc/SPTPS
+++ b/doc/SPTPS
@@ -18,8 +18,8 @@ Stream record layer
 
 A record consists of these fields:
 
-- uint32_t seqno (network byte order)
-- uint16_t length (network byte order)
+- uint32_t seqno (little endian)
+- uint16_t length (little endian)
 - uint8_t type
 - opaque data[length]
 - opaque hmac[HMAC_SIZE] (HMAC over all preceding fields)
@@ -45,8 +45,8 @@ Datagram record layer
 
 A record consists of these fields:
 
-- uint16_t length (network byte order)
-- uint32_t seqno (network byte order)
+- uint16_t length (little endian)
+- uint32_t seqno (little endian)
 - uint8_t type
 - opaque data[length]
 - opaque hmac[HMAC_SIZE] (HMAC over all preceding fields)
@@ -75,7 +75,7 @@ SIG ->
 ...encrypt and HMAC using session keys from now on...
 
 App ->
-            <- App 
+            <- App
 ...
             ...
 
@@ -91,7 +91,7 @@ ACK ->
 ...encrypt and HMAC using new session keys from now on...
 
 App ->
-            <- App 
+            <- App
 ...
             ...
 ---------------------
@@ -102,7 +102,11 @@ connection.
 
 Key EXchange message:
 
-- uint8_t kex_version (always 0 in this version of SPTPS)
+- uint8_t kex_version (always 1 in this version of SPTPS)
+- uint8_t
+  - high 4 bits: public key algorithm
+  - low 4 bits: preferred cipher suite
+- uint16_t bitmask of cipher suites supported
 - opaque nonce[32] (random number)
 - opaque ecdh_key[ECDH_SIZE]
 
@@ -124,7 +128,7 @@ Remarks:
 - After receiving the other's SIG message, the signature is verified. If it is
   correct, the shared secret is calculated from the public keys exchanged in the
   KEX message using the Elliptic Curve Diffie-Helman algorithm.
-- The shared secret key is expanded using a PRF. Both nonces and an application
+- The shared secret key is expanded using a PRF. Both nonces and the application
   specific label are also used as input for the PRF.
 - An ACK message is sent only when doing key renegotiation, and is sent using
   the old encryption keys.
@@ -135,6 +139,7 @@ The signature is calculated over this string:
 - uint8_t initiator (0 = local peer, 1 = remote peer is initiator)
 - opaque remote_kex_message[1 + 32 + ECDH_SIZE]
 - opaque local_kex_message[1 + 32 + ECDH_SIZE]
+- opaque label[label_length]
 
 The PRF is calculated as follows:
 
@@ -161,9 +166,34 @@ The expanded key is used as follows:
 Where initiator_cipher_key is the key used by session initiator to encrypt
 messages sent to the responder.
 
+Public key suites
+-----------------
+
+0: Ed25519 + SHA512
+1: Ed448 + SHAKE256?
+
+Symmetric cipher suites
+-----------------------
+
+Value in parentheses is the static priority used to break ties in cipher suite
+negotiation. We favor those algorithms that run faster without hardware
+acceleration.
+
+0: Chacha20-Poly1305 (1)
+1: AES256-GCM        (0)
+
+Cipher suite selection
+----------------------
+
+Public key suites are required to match on both sides. The symmetric suite is chosen as follows:
+
+1. AND the supported cipher suite bitmasks
+2. If both preferred cipher suites are possible, choose the one with the highest static priority.
+3. If only one is possible, choose that one.
+4. If none is possible, choose the suite from the resulting bitmask that has the highest static priority.
+
 TODO:
 -----
 
 - Document format of ECDH public key, ECDSA signature
-- Document how CTR mode is used
 - Refer to TLS RFCs where appropriate