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.9 by root, Wed Jul 10 01:51:40 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. VPE 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
148The encryption is done on SEQNO+DATA in CTR mode with IV generated from
149the seqno (for AES: seqno || seqno || seqno || (u32)0), which ensures
150uniqueness for a given key.
151
151=head2 The authentication protocol 152=head2 The authentication/key exchange protocol
152 153
153Before nodes can exchange packets, they need to establish authenticity of 154Before nodes can exchange packets, they need to establish authenticity of
154the 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
155RSA keys of all other nodes. 156RSA keys of all other nodes.
156 157
157A host establishes a simplex connection by sending the other node an RSA 158When a node wants to establish a connection to another node, it sends an
158encrypted challenge containing a random challenge (consisting of the 159RSA-OEAP-encrypted challenge and an ECDH (curve25519) key. The other node
159encryption and authentication keys to use when sending packets, more 160replies with its own ECDH key and a HKDF of the challenge and both ECDH
160random data and PKCS1_OAEP padding) and a random 16 byte "challenge-id" 161keys to prove its identity.
161(used to detect duplicate auth packets). The destination node will respond
162by replying with an (unencrypted) hash of the decrypted challenge, which
163will authenticate that node. The destination node will also set the
164outgoing encryption parameters as given in the packet.
165 162
166When the source node receives a correct auth reply (by verifying the 163The remote node enganges in exactly the same protocol. When both nodes
167hash and the id, which will expire after 120 seconds), it will start to 164have exchanged their challenge and verified the response, they calculate a
168accept data packets from the destination node. 165cipher key and a HMAC key and start exchanging data packets.
169 166
170This means that a node can only initiate a simplex connection, telling the 167In detail, the challenge consist of:
171other side the key it has to use when it sends packets. The challenge
172reply is only used to set the current IP address of the other side and
173protocol parameters.
174 168
175This protocol is completely symmetric, so to be able to send packets the 169 RSA-OAEP (SEQNO MAC CIPHER SALT EXTRA-AUTH) ECDH1
176destination node must send a challenge in the exact same way as already 170
177described (so, in essence, two simplex connections are created per node 171That is, it encrypts (with the public key of the remote node) an initial
178pair). 172sequence number for data packets, key material for the HMAC key, key
173material for the cipher key, a salt used by the HKDF (as shown later) and
174some extra random bytes that are unused except for authentication. It also
175sends the public key of a curve25519 exchange.
176
177The remote node decrypts the RSA data, generates its own ECDH key (ECDH2),
178and replies with:
179
180 HKDF-Expand (HKDF-Extract (ECDH2, RSA), ECDH1, AUTH_DIGEST_SIZE) ECDH2
181
182That is, it extracts from the decrypted RSA challenge, using its ECDH
183key as salt, and then expands using the requesting node's ECDH1 key. The
184resulting hash is returned as a proof that the node could decrypt the RSA
185challenge data, together with the ECDH key.
186
187After both nodes have done this to each other, they calculate the shared
188ECDH secret, cipher and HMAC keys for the session (each node generates two
189cipher and HMAC keys, one for sending and one for receiving).
190
191The HMAC key for sending is generated as follow:
192
193 HMAC_KEY = HKDF-Expand (HKDF-Extract (REMOTE_SALT, MAC ECDH_SECRET), info, HMAC_MD_SIZE)
194
195It extracts from MAC and ECDH_SECRET using the I<remote> SALT, then
196expands using a static info string.
197
198The cipher key is generated in the same way, except using the CIPHER part
199of the original challenge.
200
201The result of this process is to authenticate each node to the other
202node, while exchanging keys using both RSA and ECDH, the latter providing
203perfect forward secrecy.
204
205The protocol has been overdesigned where this was possible without
206increasing implementation complexity, in an attempt to protect against
207implementation or protocol failures. For example, if the ECDH challenge
208was found to be flawed, perfect forward secrecy would be lost, but the
209data would likely still be protected. Likewise, standard algorithms and
210implementations are used where possible.
179 211
180=head2 Retrying 212=head2 Retrying
181 213
182When 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
183requests in bursts with an exponential back-off. After some time it will 215requests in bursts with an exponential back-off. After some time it will
… …
230 262
231=item Failing all that, the packet will be dropped. 263=item Failing all that, the packet will be dropped.
232 264
233=back 265=back
234 266
235A host can usually declare itself unreachable directly by setting it's 267A host can usually declare itself unreachable directly by setting its
236port 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
237a config-file that disables all protocols for these other hosts. Another 269a config-file that disables all protocols for these other hosts. Another
238option 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.
239 271
240If 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)
… …
246connection to the other peer, which is usually possible even when both 278connection to the other peer, which is usually possible even when both
247hosts are behind a NAT gateway. 279hosts are behind a NAT gateway.
248 280
249Routing via other nodes works because the SRCDST field is not encrypted, 281Routing via other nodes works because the SRCDST field is not encrypted,
250so 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
251each 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
252decrypt 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
253protocol translator. 285protocol translator.
254 286
255 287

Diff Legend

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