git.meshlink.io Git - meshlink/blob - doc/SPTPS

   1 Simple Peer-to-Peer Security
   2 ----------------------------
   3
   4 SPTPS is a protocol that, like TLS, aims to provide a secure transport layer
   5 for applications. However, it is specifically aimed at peer-to-peer
   6 applications. Specifically, peers have each other's credentials beforehand,
   7 they need not negotiate certificates. Also, the security parameters of the
   8 application is also known beforehand, so they need not negotiate cipher suites.
   9 Only one cipher suite is available, and only one authentication method is used.
  10 This not only greatly simplifies the protocol, it also gets rid of an entire
  11 class of attacks and possible programming mistakes.
  12
  13 SPTPS can be used both on top of reliable stream protocols such as TCP or on
  14 top of datagram protocols such as UDP.
  15
  16 Stream record layer
  17 -------------------
  18
  19 A record consists of these fields:
  20
  21 - uint32_t seqno (network byte order)
  22 - uint16_t length (network byte order)
  23 - uint8_t type
  24 - opaque data[length]
  25 - opaque hmac[HMAC_SIZE] (HMAC over all preceding fields)
  26
  27 Remarks:
  28
  29 - The seqno field is never sent to the peer, but is included in the calculation
  30   of the HMAC.
  31 - At the start of the session, the HMAC field does not appear until after the
  32   SIGnature records have been exchanged.
  33 - After the authentication phase, the type and data fields are encrypted before
  34   the HMAC is calculated.
  35
  36 Message type:
  37
  38 - 0..127 represent application records. The meaning of the value is application
  39   specific.
  40 - 128 is a handshake record.
  41 - 129..255 are reserved and never to be used for application records.
  42
  43 Datagram record layer
  44 ---------------------
  45
  46 A record consists of these fields:
  47
  48 - uint16_t length (network byte order)
  49 - uint32_t seqno (network byte order)
  50 - uint8_t type
  51 - opaque data[length]
  52 - opaque hmac[HMAC_SIZE] (HMAC over all preceding fields)
  53
  54 Remarks:
  55
  56 - The length field is never sent to the peer, but is included in the calculation
  57   of the HMAC.
  58 - The rest is the same as the stream record layer.
  59
  60 Authentication protocol
  61 -----------------------
  62
  63 The authentication consists of an exchange of Key EXchange, SIGnature and
  64 ACKnowledge messages, transmitted using type 128 records.
  65
  66 Overview:
  67
  68 Initiator   Responder
  69 ---------------------
  70 KEX ->
  71             <- KEX
  72 SIG ->
  73             <- SIG
  74
  75 ...encrypt and HMAC using session keys from now on...
  76
  77 App ->
  78             <- App
  79 ...
  80             ...
  81
  82 ...key renegotiation starts here...
  83
  84 KEX ->
  85             <- KEX
  86 SIG ->
  87             <- SIG
  88 ACK ->
  89             <- ACK
  90
  91 ...encrypt and HMAC using new session keys from now on...
  92
  93 App ->
  94             <- App
  95 ...
  96             ...
  97 ---------------------
  98
  99 Note that the responder does not need to wait before it receives the first KEX
 100 message, it can immediately send its own once it has accepted an incoming
 101 connection.
 102
 103 Key EXchange message:
 104
 105 - uint8_t kex_version (always 0 in this version of SPTPS)
 106 - opaque nonce[32] (random number)
 107 - opaque ecdh_key[ECDH_SIZE]
 108
 109 SIGnature message:
 110
 111 - opaque ecdsa_signature[ECDSA_SIZE]
 112
 113 ACKnowledge message:
 114
 115 - empty (only sent after key renegotiation)
 116
 117 Remarks:
 118
 119 - At the start, both peers generate a random nonce and an Elliptic Curve public
 120   key and send it to the other in the KEX message.
 121 - After receiving the other's KEX message, both KEX messages are concatenated
 122   (see below), and the result is signed using ECDSA. The result is sent to the
 123   other.
 124 - After receiving the other's SIG message, the signature is verified. If it is
 125   correct, the shared secret is calculated from the public keys exchanged in the
 126   KEX message using the Elliptic Curve Diffie-Helman algorithm.
 127 - The shared secret key is expanded using a PRF. Both nonces and the application
 128   specific label are also used as input for the PRF.
 129 - An ACK message is sent only when doing key renegotiation, and is sent using
 130   the old encryption keys.
 131 - The expanded key is used to key the encryption and HMAC algorithms.
 132
 133 The signature is calculated over this string:
 134
 135 - uint8_t initiator (0 = local peer, 1 = remote peer is initiator)
 136 - opaque remote_kex_message[1 + 32 + ECDH_SIZE]
 137 - opaque local_kex_message[1 + 32 + ECDH_SIZE]
 138 - opaque label[label_length]
 139
 140 The PRF is calculated as follows:
 141
 142 - A HMAC using SHA512 is used, the shared secret is used as the key.
 143 - For each block of 64 bytes, a HMAC is calculated. For block n: hmac[n] =
 144   HMAC_SHA512(hmac[n - 1] + seed)
 145 - For the first block (n = 1), hmac[0] is given by HMAC_SHA512(zeroes + seed),
 146   where zeroes is a block of 64 zero bytes.
 147
 148 The seed is as follows:
 149
 150 - const char[13] "key expansion"
 151 - opaque responder_nonce[32]
 152 - opaque initiator_nonce[32]
 153 - opaque label[label_length]
 154
 155 The expanded key is used as follows:
 156
 157 - opaque responder_cipher_key[CIPHER_KEYSIZE]
 158 - opaque responder_digest_key[DIGEST_KEYSIZE]
 159 - opaque initiator_cipher_key[CIPHER_KEYSIZE]
 160 - opaque initiator_digest_key[DIGEST_KEYSIZE]
 161
 162 Where initiator_cipher_key is the key used by session initiator to encrypt
 163 messages sent to the responder.
 164
 165 TODO:
 166 -----
 167
 168 - Document format of ECDH public key, ECDSA signature
 169 - Document how CTR mode is used
 170 - Refer to TLS RFCs where appropriate