commit 6f10de09ac3e708c66e675ed6ece9938aa5ef9e3
parent a2cfbb01ad81f9e9cd99cd9fdd9f58e7c78557a4
Author: Pedram Fardzadeh <p.fardzadeh@protonmail.com>
Date: Mon, 15 Jul 2024 03:45:25 +0200
Pooled FIXME's
Diffstat:
1 file changed, 113 insertions(+), 27 deletions(-)
diff --git a/draft-gnunet-communicators.xml b/draft-gnunet-communicators.xml
@@ -195,14 +195,14 @@
TRANSPORT.
In the other direction, communicators may allow TRANSPORT to give
back-pressure towards the communicator by providing a non-NULL
- GNUNET_TRANSPORT_MessageCompletedCallback (FIXME generic API) argument to the
- GNUNET_TRANSPORT_communicator_receive (FIXME generic API) function.
+ GNUNET_TRANSPORT_MessageCompletedCallback argument to the
+ GNUNET_TRANSPORT_communicator_receive function.
In this case, TRANSPORT will only invoke this function once it has
processed the message and is ready to receive more.
Communicators should then limit how much traffic they receive based on
this backpressure.
Note that communicators do not have to provide a
- GNUNET_TRANSPORT_MessageCompletedCallback (FIXME generic API);
+ GNUNET_TRANSPORT_MessageCompletedCallback;
for example, UDP cannot support back-pressure due to the nature of the
UDP protocol.
In this case, TRANSPORT will implement its own TRANSPORT-to-TRANSPORT
@@ -264,12 +264,13 @@ KeyGenElligator():
point and are are defined in the following.
The obfuscated curve point is called the Elligator "Representative".
Let A and P be the parameters for Curve25519 as specified in section 4.1 of <xref target="RFC7748"/>.
- Further, let X be any valid x-coordinate of a Curve25519 point, sqrt() a function which calculates the
- square root of the finite field element, U the number sqrt(-1) which is a non-quadratic number in the finite field,
- and L() a function which computes the legendre symbol of a field element.
- As each of the field elements have two roots, we need to define the notion of negative and non-negative numbers.
- This is especially important for the sqrt() function.
- A straightforward choice is to define the set {0,..., (P - 1) / 2} as set of all non-negative numbers.
+ Further, let X be any valid x-coordinate of a Curve25519 point, L() a function which computes the legendre symbol
+ of a field element with regard to the odd prime P.
+ In order for the square root operation sqrt within the encoding function to work deterministically, we need to
+ define the notion of positive and negative numbers within the field. There are multiple valid ways to partition
+ the field elements, but a common choice is to define the set {0,..., (P-1)/2} as the set of positive numbers,
+ and {(P-1)/2 + 1,…,P−1} as the set of the negative numbers. The elligator implementations of both peers <bcp14>MUST</bcp14>
+ use the same definition regarding positive and negative numbers to be interoperable.
The encoding function algorithm is:
</t>
<artwork name="" type="" align="left" alt=""><![CDATA[
@@ -399,8 +400,8 @@ Decaps(x, A):
</t>
<t>
There are three distinct message types that are sent and received by UDP communicators: KX, BOX and BROADCAST.
- For KX and BOX messages, their metadata is chosen such that they are indistinguishable from random. (FIXME:
- not the case for BROADCAST).
+ For KX and BOX messages, their metadata is chosen such that they are indistinguishable from random. This property
+ does not hold for BROADCAST messages and is not necessary, as they are only sent within a local area network.
</t>
<section anchor="Key_exchange" numbered="true" toc="default">
@@ -498,7 +499,7 @@ Decaps(x, A):
</dd>
<dt>MONOTONIC TIMESTAMP</dt>
<dd>
- FIXME.
+ A 64-bit value for absolute time used by GNUnet, in microseconds and in network byte order.
</dd>
<dt>PAYLOAD</dt>
<dd>
@@ -571,7 +572,7 @@ Decaps(x, A):
</dd>
<dt>MONOTONIC TIMESTAMP</dt>
<dd>
- FIXME.
+ A 64-bit value for absolute time used by GNUnet, in microseconds and in network byte order.
</dd>
</dl>
<t>
@@ -741,15 +742,15 @@ DeriveKID(MSK,SEQ):
can be decrypted. Otherwise, the message <bcp14>MUST</bcp14> be rejected.
</t>
<t>
- Multiple shared secrets can be used simultaneously between the sending peer and target peer (FIXME: currently limited to 256). Should the
+ Multiple shared secrets can be used simultaneously between the sending peer and target peer. Should the
sending peer use up all acknowledgments for all its shared secrets, messages are sent through KX messages again.
</t>
</section>
<section anchor="udp_rekeying" numbered="true" toc="default">
<name>Rekeying</name>
<t>
- The amount of data which can be encrypted with a shared secret <bcp14>MUST</bcp14> be limited (FIXME: Currently at 4GB). Before
- the capacity of a shared secret is used up (FIXME: currently at 70%), the sender initiates rekeying by sending a new ephemeral public key
+ The amount of data which can be encrypted with a shared secret <bcp14>MUST</bcp14> be limited. Before
+ the capacity of a shared secret is used up, the sender initiates rekeying by sending a new ephemeral public key
for a key exchange. As multiple shared secrets can be used simultaneously, rekeying doesn't necessarily delete the old shared secret if its
capacity is not yet reached. The ephemeral public key is sent encrypted in a Rekey header as part of the payload of BOX message. Because the
ephemeral public key is encrypted, there is no need to use Elligator's encoding function. The wire format of the Rekey header can
@@ -794,8 +795,81 @@ DeriveKID(MSK,SEQ):
<section anchor="udp_bc" numbered="true" toc="default">
<name>Broadcast</name>
<t>
- (FIXME: Broadcast documentation is missing)
+ BROADCAST messages are sent by peers to announce their presence. Those messages are only distributed in the LAN and sent in cleartext.
</t>
+ <figure anchor="figure_udp_broadcast" title="The binary representation of the udp BROADCAST message">
+ <artwork name="" type="" align="left" alt=""><![CDATA[
+0 8 16 24 32 40 48 56
++-----+-----+-----+-----+-----+-----+-----+-----+
+| |
+| SENDER PEER ID |
+| |
+| |
++-----+-----+-----+-----+-----+-----+-----+-----+
+| |
+| SIGNATURE |
+| |
+| |
+| |
+| |
+| |
+| |
++-----+-----+-----+-----+-----+-----+-----+-----+
+ ]]></artwork>
+ </figure>
+ <dl>
+ <dt>SENDER PEER ID</dt>
+ <dd>
+ A 256-bit EdDSA public key.
+ </dd>
+ <dt>SIGNATURE</dt>
+ <dd>
+ The EdDSA signature is computed with the announced peer private key
+ over the peer identity and address hash as depicted in <xref target="figure_udp_broadcast_sig"/>.
+ </dd>
+ </dl>
+ <figure anchor="figure_udp_broadcast_sig" title="The wire format of the data structure over which the signature of the UDP BROADCAST message is computed.">
+ <artwork name="" type="" align="left" alt=""><![CDATA[
+0 8 16 24 32 40 48 56
++-----+-----+-----+-----+-----+-----+-----+-----+
+| SIZE | PURPOSE (0x0X) |
++-----+-----+-----+-----+-----+-----+-----+-----+
+| SENDER PEER ID |
+| |
+| |
+| |
++-----+-----+-----+-----+-----+-----+-----+-----+
+| ADDRESS HASH |
+| |
+| |
+| |
++-----+-----+-----+-----+-----+-----+-----+-----+
+ ]]></artwork>
+ </figure>
+ <dl>
+ <dt>SIZE</dt>
+ <dd>
+ A 32-bit value containing the length of the signed data in bytes
+ in network byte order.
+ </dd>
+ <dt>PURPOSE</dt>
+ <dd>
+ A 32-bit signature purpose flag in network byte order. The value of this
+ field <bcp14>MUST</bcp14> be 34. It defines the context in which
+ the signature is created so that it cannot be reused in other parts
+ of the protocol including possible future extensions.
+ The value of this field corresponds to an entry in the
+ GANA "GNUnet Signature Purpose" registry <xref target="gana"/>.
+ </dd>
+ <dt>SENDER PEER ID</dt>
+ <dd>
+ A 256-bit EdDSA public key.
+ </dd>
+ <dt>ADDRESS HASH</dt>
+ <dd>
+ Hash of the sender's UDP address.
+ </dd>
+ </dl>
</section>
</section>
<section anchor="tcp_comm" numbered="true" toc="default">
@@ -869,7 +943,7 @@ DeriveKID(MSK,SEQ):
</dd>
<dt>MONOTONIC TIMESTAMP</dt>
<dd>
- FIXME.
+ A 64-bit value for absolute time used by GNUnet, in microseconds and in network byte order.
</dd>
<dt>NONCE</dt>
<dd>
@@ -945,7 +1019,7 @@ DeriveKID(MSK,SEQ):
</dd>
<dt>MONOTONIC TIMESTAMP</dt>
<dd>
- FIXME.
+ A 64-bit value for absolute time used by GNUnet, in microseconds and in network byte order.
</dd>
<dt>NONCE</dt>
<dd>
@@ -955,7 +1029,7 @@ DeriveKID(MSK,SEQ):
<t>
Upon reception of the ephemeral public key, the receiving TCP communicator carries out the decapsulation step of the
key exchange and retrieves the shared key material. The subsequently received TCP handshake message is then decrypted and verified.
- If the signature is invalid, the connection is dropped. (FIXME: Other checks such as sender peer identity etc needed).
+ If the signature is invalid, the connection is dropped.
In the case of a valid signature, the receiving TCP communicator sends its own TCP handshake message to establish
shared key material for outgoing messages and also replies with an encrypted TCP handshake acknowledgment message as defined
in <xref target="figure_tcp_handshake_ack"/>.
@@ -1033,7 +1107,7 @@ DeriveKID(MSK,SEQ):
</dd>
<dt>MONOTONIC TIMESTAMP</dt>
<dd>
- FIXME.
+ A 64-bit value for absolute time used by GNUnet, in microseconds and in network byte order.
</dd>
<dt>NONCE</dt>
<dd>
@@ -1100,7 +1174,7 @@ DeriveKID(MSK,SEQ):
</dd>
<dt>MONOTONIC TIMESTAMP</dt>
<dd>
- FIXME.
+ A 64-bit value for absolute time used by GNUnet, in microseconds and in network byte order.
</dd>
<dt>NONCE</dt>
<dd>
@@ -1162,9 +1236,6 @@ SetupCipher(REC_ID, MSK):
<xref target="tcp_rekeying"/>. The necessary key exchanges to establish the new key material are protected using monotonic
timestamps.
</t>
- <t>
- (FIXME: hmac, MtE discussion, padding-oracle).
- </t>
<figure anchor="figure_tcp_box" title="The binary representation of the TCP BOX message.">
<artwork name="" type="" align="left" alt=""><