I2P_Developers/i2p.www
3
0
Fork 5
Code Issues 27 Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Prop. 159 hole punch updates

Browse Source 
SSU spec: add more info on changes in 0.9.50
This commit is contained in:
zzz
2022-05-02 12:04:44 -04:00
parent 2df96f417b
commit c1adc7ef1f
2 changed files with 142 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
i2p2www/pages/site/docs/transport/ssu.html
View File

@ -1,7 +1,7 @@
{% extends "global/layout.html" %}
{% block title %}{% trans %}Secure Semireliable UDP{% endtrans %} (SSU){% endblock %}
{% block lastupdated %}2021-10{% endblock %}
{% block accuratefor %}0.9.52{% endblock %}
{% block lastupdated %}2022-05{% endblock %}
{% block accuratefor %}0.9.54{% endblock %}
{% block content %}
<p>{% trans transports=site_url('docs/transport'), ntcp=site_url('docs/transport/ntcp'), ntcp2=site_url('docs/spec/ntcp2') -%}
@ -527,10 +527,18 @@ and Alice-Bob and Alice-Charlie communication may be via IPv6,
if Bob and Charlie indicate support with a 'B' capability in their published IPv6 address.
See <a href="/spec/proposals/126-ipv6-peer-testing">Proposal 126</a> for details.
</p><p>
Prior to release 0.9.50,
Alice sends the request to Bob using an existing session over the transport (IPv4 or IPv6) that she wishes to test.
When Bob receives a request from Alice via IPv4, Bob must select a Charlie that advertises an IPv4 address.
When Bob receives a request from Alice via IPv6, Bob must select a Charlie that advertises an IPv6 address.
The actual Bob-Charlie communication may be via IPv4 or IPv6 (i.e., independent of Alice's address type).
</p><p>
As of release 0.9.50,
If the message is over IPv6 for an IPv4 introduction,
or (as of release 0.9.50) over IPv4 for an IPv6 introduction,
Alice must include her introduction address and port.
See <a href="/spec/proposals/158">Proposal 158</a> for details.
</p>

144
i2p2www/spec/proposals/159-ssu2.rst
View File

@ -5,7 +5,7 @@ SSU2
:author: eyedeekay, orignal, zlatinb, zzz
:created: 2021-09-12
:thread: http://zzz.i2p/topics/2612
:lastupdated: 2022-04-30
:lastupdated: 2022-05-02
:status: Open
:target: 0.9.56
@ -2237,6 +2237,10 @@ correlate the HolePunch with Charlie.
Four byte nonce may need to be replaced or supplemented by
8-byte connection ID.
The empty Hole Punch message is unique and may be used
by on-path observers to identify the protocol, this should be
changed.
Peer Test Security
---------------------
@ -2664,7 +2668,7 @@ The "packet header" is the part after the IP/UDP header.
TODO except fragmented Session Confirmed
All SSU2 messages are at least 40 bytes in length, except for Hole Punch which is empty.
All SSU2 messages are at least 40 bytes in length.
Any message of length 1-39 bytes is invalid.
All SSU2 messages are less than or equal to 1472 (IPv4) or 1452 (IPv6) bytes in length. The message
format is based on Noise messages, with modifications for framing and indistinguishability.
@ -2684,7 +2688,7 @@ Type Message Header Length Header Encr. Length
7 PeerTest 32 32
9 Retry 32 32
10 Token Request 32 32
n/a HolePunch 0 0
11 HolePunch 32 32
==== ================ ============= =============
@ -3065,7 +3069,7 @@ For Retry, bytes 16-31 of the long header
are encrypted using ChaCha20.
The unencrypted data is random, so the encrypted data will appear to be random.
There are six header protection key phases:
There are seven header protection key phases:
- Session Request and Token Request
- Session Created
@ -3073,6 +3077,7 @@ There are six header protection key phases:
- Session Confirmed
- Data Phase
- Peer Test
- Hole Punch
================= =================== ====================
@ -3086,6 +3091,7 @@ Retry Bob Intro Key Bob Intro Key
Data Alice/Bob Intro Key See data phase KDF
Peer Test 5,7 Alice Intro Key Alice Intro Key
Peer Test 6 Charlie Intro Key Charlie Intro Key
Hole Punch Alice Intro Key Alice Intro Key
================= =================== ====================
@ -4867,16 +4873,124 @@ Notes
Hole Punch Message
KDF for Hole Punch
--------------------------
This message must be fast to generate, using symmetric encryption only.
.. raw:: html
{% highlight lang='text' %}
// AEAD parameters
// aik = Alice's intro key
k = aik
n = 4 byte packet number from header
ad = 32 byte header, before header encryption
ciphertext = ENCRYPT(k, n, payload, ad)
// Header encryption keys for this message
k_header_1 = aik
k_header_2 = aik
{% endhighlight %}
Hole Punch (Type 11)
-------------------------------
An empty datagram. No content. Same as SSU 1.
A HolePunch is simply a UDP packet with no data. It is unauthenticated and
unencrypted. It does not contain a SSU header, so it does not have a message
type number. It is sent from Charlie to Alice as a part of the Introduction
sequence.
Charlie sends to Alice, in response to a Relay Intro received from Bob.
Alice responds with a new Session Request.
Size: 48 + payload size.
Noise payload: See below.
Raw contents:
.. raw:: html
{% highlight lang='dataspec' %}
+----+----+----+----+----+----+----+----+
| Long Header bytes 0-15, ChaCha20 |
+ encrypted with Alice intro key +
| |
+----+----+----+----+----+----+----+----+
| Long Header bytes 16-31, ChaCha20 |
+ encrypted with Alice intro key +
| |
+----+----+----+----+----+----+----+----+
| |
+ +
| ChaCha20 encrypted data |
+ (length varies) +
| |
+ see KDF for key and n +
| see KDF for associated data |
+----+----+----+----+----+----+----+----+
| |
+ Poly1305 MAC (16 bytes) +
| |
+----+----+----+----+----+----+----+----+
{% endhighlight %}
Unencrypted data (Poly1305 authentication tag not shown):
.. raw:: html
{% highlight lang='dataspec' %}
+----+----+----+----+----+----+----+----+
| Destination Connection ID |
+----+----+----+----+----+----+----+----+
| Packet Number |type| ver| id |flag|
+----+----+----+----+----+----+----+----+
| Source Connection ID |
+----+----+----+----+----+----+----+----+
| Token |
+----+----+----+----+----+----+----+----+
| ChaCha20 payload (block data) |
+ (length varies) +
| see below for allowed blocks |
+----+----+----+----+----+----+----+----+
Destination Connection ID :: See below
Packet Number :: Random number generated by Charlie
type :: 11
ver :: 2
id :: 1 byte, the network ID (currently 2, except for test networks)
flag :: 1 byte, unused, set to 0 for future compatibility
Source Connection ID :: See below
Token :: 8 byte unsigned integer, randomly generated by Charlie, nonzero.
Identical to the token sent in the Relay Response.
{% endhighlight %}
Payload
```````
- DateTime block
- Address block
- Padding block (optional)
The minimum payload size is 8 bytes. Since the DateTime and Address blocks
total more than that, the requirement is met with only those two blocks.
Connection IDs: The two connection IDs are derived from the test nonce.
The Destination Connection ID
is two copies of the 4-byte relay nonce, i.e. ((nonce << 32) | nonce).
The Source Connection ID is the inverse of the Destination Connection ID,
i.e. ~((nonce << 32) | nonce).
TODO should it be a real peer test message instead?
@ -5472,6 +5586,8 @@ See Relay Process section below.
~ ~
| . . . |
+----+----+----+----+----+----+----+----+
| Token |
+----+----+----+----+----+----+----+----+
blk :: 8
size :: 2 bytes, 6
@ -5516,7 +5632,11 @@ See Relay Process section below.
signature :: length varies, 64 bytes for Ed25519.
Signature of prologue, Bob's hash,
and signed data above, as signed by
Alice.
Charlie.
Not present if rejected by Bob.
token :: Token generated by Charlie for Alice to use
in the Session Request.
Only present if code is 0 (accept)
{% endhighlight %}