ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/gvpe.protocol.7.pod
(Generate patch)

Comparing gvpe/doc/gvpe.protocol.7.pod (file contents):
Revision 1.12 by root, Fri Jul 19 21:13:44 2013 UTC vs.
Revision 1.15 by root, Thu Jan 29 00:21:39 2015 UTC

… …
6protocol which is used to authenticate tunnels and send encrypted data 6protocol which is used to authenticate tunnels and send encrypted data
7packets. This protocol is described in more detail the second part of this 7packets. This protocol is described in more detail the second part of this
8document. 8document.
9 9
10The first part of this document describes the transport protocols which 10The first part of this document describes the transport protocols which
11are used by GVPE to send it's data packets over the network. 11are used by GVPE to send its data packets over the network.
12 12
13=head1 PART 1: Transport protocols 13=head1 PART 1: Transport protocols
14 14
15GVPE offers a wide range of transport protocols that can be used to 15GVPE offers a wide range of transport protocols that can be used to
16interchange data between nodes. Protocols differ in their overhead, speed, 16interchange data between nodes. Protocols differ in their overhead, speed,
… …
54It should be used if RAW IP is not available. 54It should be used if RAW IP is not available.
55 55
56=head2 TCP 56=head2 TCP
57 57
58This protocol is a very bad choice, as it not only has high overhead (more 58This protocol is a very bad choice, as it not only has high overhead (more
59than 60 bytes), but the transport also retries on it's own, which leads 59than 60 bytes), but the transport also retries on its own, which leads
60to congestion when the link has moderate packet loss (as both the TCP 60to congestion when the link has moderate packet loss (as both the TCP
61transport and the tunneled traffic will retry, increasing congestion more 61transport and the tunneled traffic will retry, increasing congestion more
62and more). It also has high latency and is quite inefficient. 62and more). It also has high latency and is quite inefficient.
63 63
64It's only useful when tunneling through firewalls that block better 64It's only useful when tunneling through firewalls that block better
… …
120 +------+------+--------+------+ 120 +------+------+--------+------+
121 | HMAC | TYPE | SRCDST | DATA | 121 | HMAC | TYPE | SRCDST | DATA |
122 +------+------+--------+------+ 122 +------+------+--------+------+
123 123
124The HMAC field is present in all packets, even if not used (e.g. in auth 124The HMAC field is present in all packets, even if not used (e.g. in auth
125request packets), in which case it is set to all zeroes. The checksum 125request packets), in which case it is set to all zeroes. The MAC itself is
126itself is calculated over the TYPE, SRCDST and DATA fields in all cases. 126calculated over the TYPE, SRCDST and DATA fields in all cases.
127 127
128The TYPE field is a single byte and determines the purpose of the packet 128The TYPE field is a single byte and determines the purpose of the packet
129(e.g. RESET, COMPRESSED/UNCOMPRESSED DATA, PING, AUTH REQUEST/RESPONSE, 129(e.g. RESET, COMPRESSED/UNCOMPRESSED DATA, PING, AUTH REQUEST/RESPONSE,
130CONNECT REQUEST/INFO etc.). 130CONNECT REQUEST/INFO etc.).
131 131
… …
134 134
135The DATA portion differs between each packet type, naturally, and is the 135The DATA portion differs between each packet type, naturally, and is the
136only part that can be encrypted. Data packets contain more fields, as 136only part that can be encrypted. Data packets contain more fields, as
137shown: 137shown:
138 138
139 +------+------+--------+------+-------+------+ 139 +------+------+--------+-------+------+
140 | HMAC | TYPE | SRCDST | RAND | SEQNO | DATA | 140 | HMAC | TYPE | SRCDST | SEQNO | DATA |
141 +------+------+--------+------+-------+------+ 141 +------+------+--------+-------+------+
142
143RAND is a sequence of fully random bytes, used to increase the entropy of
144the data for encryption purposes.
145 142
146SEQNO is a 32-bit sequence number. It is negotiated at every connection 143SEQNO is a 32-bit sequence number. It is negotiated at every connection
147initialization and starts at some random 31 bit value. GVPE currently uses 144initialization and starts at some random 31 bit value. GVPE currently uses
148a sliding window of 512 packets/sequence numbers to detect reordering, 145a sliding window of 512 packets/sequence numbers to detect reordering,
149duplication and replay attacks. 146duplication and replay attacks.
150 147
151The encryption is done on RAND+SEQNO+DATA in CBC mode with zero IV (or, 148The encryption is done on SEQNO+DATA in CTR mode with IV generated from
152equivalently, the IV is RAND+SEQNO, encrypted with the block cipher, 149the seqno (for AES: seqno || seqno || seqno || (u32)0), which ensures
153unless RAND size is decreased or increased over the default value). 150uniqueness for a given key.
154
155The random prefix itself is generated by using AES in CTR mode with a
156random key and starting value, which should make them unpredictable even
157before encrypting them again. The sequence number additionally ensures
158that the IV is unique.
159 151
160=head2 The authentication/key exchange protocol 152=head2 The authentication/key exchange protocol
161 153
162Before nodes can exchange packets, they need to establish authenticity of 154Before nodes can exchange packets, they need to establish authenticity of
163the other side and a key. Every node has a private RSA key and the public 155the other side and a key. Every node has a private RSA key and the public
164RSA keys of all other nodes. 156RSA keys of all other nodes.
165 157
166When a node wants to establish a connection to another node, it sends an 158When a node wants to establish a connection to another node, it sends an
167RSA-OEAP-encrypted challenge and an ECDH key. The other node replies with 159RSA-OEAP-encrypted challenge and an ECDH (curve25519) key. The other node
168it's own ECDH key and a HKDF of the challange and both ECDH keys to proof 160replies with its own ECDH key and a HKDF of the challenge and both ECDH
169it's identity. 161keys to prove its identity.
170 162
171The remote node enganges in exactly the same protocol. When both nodes 163The remote node enganges in exactly the same protocol. When both nodes
172have exchanged their challenge and verified the response, they calculate a 164have exchanged their challenge and verified the response, they calculate a
173cipher key and a HMAC key and start exchanging data packets. 165cipher key and a HMAC key and start exchanging data packets.
174 166
… …
180sequence number for data packets, key material for the HMAC key, key 172sequence number for data packets, key material for the HMAC key, key
181material for the cipher key, a salt used by the HKDF (as shown later) and 173material for the cipher key, a salt used by the HKDF (as shown later) and
182some extra random bytes that are unused except for authentication. It also 174some extra random bytes that are unused except for authentication. It also
183sends the public key of a curve25519 exchange. 175sends the public key of a curve25519 exchange.
184 176
185The remote node decrypts the RSA data, generates it's own ECDH key (ECDH2), and 177The remote node decrypts the RSA data, generates its own ECDH key (ECDH2),
186replies with: 178and replies with:
187 179
188 HKDF-Expand (HKDF-Extract (ECDH2, RSA), ECDH1, AUTH_DIGEST_SIZE) ECDH2 180 HKDF-Expand (HKDF-Extract (ECDH2, RSA), ECDH1, AUTH_DIGEST_SIZE) ECDH2
189 181
190That is, it extracts from the decrypted RSA challenge, using it's ECDH 182That is, it extracts from the decrypted RSA challenge, using its ECDH
191key as salt, and then expands using the requesting node's ECDH1 key. The 183key as salt, and then expands using the requesting node's ECDH1 key. The
192resulting has is returned as a proof that the node could decrypt the RSA 184resulting hash is returned as a proof that the node could decrypt the RSA
193challenge data, together with the ECDH key. 185challenge data, together with the ECDH key.
194 186
195After both nodes have done this to each other, they calculate the shared 187After both nodes have done this to each other, they calculate the shared
196ECDH secrets, cipher and HMAC keys for the session (each 188ECDH secret, cipher and HMAC keys for the session (each node generates two
197node generates two cipher and HMAC keys, one for sending and one for 189cipher and HMAC keys, one for sending and one for receiving).
198receiving).
199 190
200The HMAC key for sending is generated as follow: 191The HMAC key for sending is generated as follow:
201 192
202 HMAC_KEY = HKDF-Expand (HKDF-Extract (REMOTE_SALT, MAC ECDH_SECRET), info, HMAC_MD_SIZE) 193 HMAC_KEY = HKDF-Expand (HKDF-Extract (REMOTE_SALT, MAC ECDH_SECRET), info, HMAC_MD_SIZE)
203 194
… …
212perfect forward secrecy. 203perfect forward secrecy.
213 204
214The protocol has been overdesigned where this was possible without 205The protocol has been overdesigned where this was possible without
215increasing implementation complexity, in an attempt to protect against 206increasing implementation complexity, in an attempt to protect against
216implementation or protocol failures. For example, if the ECDH challenge 207implementation or protocol failures. For example, if the ECDH challenge
217was found to be flawed, perfect forward secrecy would be lost, but 208was found to be flawed, perfect forward secrecy would be lost, but the
218the data would still be protected. Likewise, standard algorithms and 209data would likely still be protected. Likewise, standard algorithms and
219implementations are used where possible. 210implementations are used where possible.
220 211
221=head2 Retrying 212=head2 Retrying
222 213
223When there is no response to an auth request, the node will send auth 214When there is no response to an auth request, the node will send auth
… …
271 262
272=item Failing all that, the packet will be dropped. 263=item Failing all that, the packet will be dropped.
273 264
274=back 265=back
275 266
276A host can usually declare itself unreachable directly by setting it's 267A host can usually declare itself unreachable directly by setting its
277port number(s) to zero. It can declare other hosts as unreachable by using 268port number(s) to zero. It can declare other hosts as unreachable by using
278a config-file that disables all protocols for these other hosts. Another 269a config-file that disables all protocols for these other hosts. Another
279option is to disable all protocols on that host in the other config files. 270option is to disable all protocols on that host in the other config files.
280 271
281If two hosts cannot connect to each other because their IP address(es) 272If two hosts cannot connect to each other because their IP address(es)
… …
287connection to the other peer, which is usually possible even when both 278connection to the other peer, which is usually possible even when both
288hosts are behind a NAT gateway. 279hosts are behind a NAT gateway.
289 280
290Routing via other nodes works because the SRCDST field is not encrypted, 281Routing via other nodes works because the SRCDST field is not encrypted,
291so the router can just forward the packet to the destination host. Since 282so the router can just forward the packet to the destination host. Since
292each host uses it's own private key, the router will not be able to 283each host uses its own private key, the router will not be able to
293decrypt or encrypt packets, it will just act as a simple router and 284decrypt or encrypt packets, it will just act as a simple router and
294protocol translator. 285protocol translator.
295 286
296 287

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines