[GNUnet-SVN] r1466 - GNUnet-docs/WWW

[grothoff]

Author: grothoff
Date: 2005-07-13 09:09:46 -0700 (Wed, 13 Jul 2005)
New Revision: 1466

Modified:
   GNUnet-docs/WWW/protocol_p2p_core.php3
   GNUnet-docs/WWW/todo
Log:
update

Modified: GNUnet-docs/WWW/protocol_p2p_core.php3
===================================================================
--- GNUnet-docs/WWW/protocol_p2p_core.php3      2005-07-13 15:21:33 UTC (rev 
1465)
+++ GNUnet-docs/WWW/protocol_p2p_core.php3      2005-07-13 16:09:46 UTC (rev 
1466)
@@ -1,7 +1,7 @@
 <?php
 include("scripts.php3");
 $title = "GNUnet Documentation: The Peer-to-Peer Protocols";
-$description="GNUnet Documentation - The core protocol";
+$description="The core protocol, the fundamental messages underlying all 
GNUnet applications";
 include("html_header.php3");
 
 ANCHOR("protocol");H3("GNUnet Protocol: node-to-node: core messages");
@@ -18,6 +18,10 @@
 LIV(extlink_("#NOISE","NOISE"));
 echo "</ul>\n";
 BP();
+W("These messages are typically not all implemented directly by the core 
itself, but rather by internal service plugins.");
+W("However, loading these plugins is not optional (the core will automatically 
do so on startup).");
+W("Thus it makes sense to refer to these messages as the core messages.");
+P();
 W("The most basic sequence is that a host sends a %s to any other host to 
notify it of its existance on the network.",
   extlink_("#HELO","HELO"));
 W("The recipient of the HELO sends back a %s to confirm that the host is 
actually reachable.",
@@ -58,25 +62,20 @@
 W("A packet exchanged between GNUnet hosts can contain any number of messages 
(only limited by the MTU of the transport layer).");
 P();
 
-W("In addition to the message itself, the transport mechanism must communicate 
the identity of the sender.");
-W("The transport layer implementation is responsible for encapsulating the 
message appropriately.");
-W("Depending on the implementation of the transport mechanism, the sender 
identity may not be transmitted for each message.");
-W("For example, a stateful transport such as TCP may only transmit the sender 
identity once at the beginning of the exchange.");
-P();
 W("In addition to encrypting the message, the GNUnet core also extends each 
message with additional information.");
 W("The GNUnet core adds a checksum, information about bandwidth limitations 
and sequencing information to prevent processing messages twice.");
 W("The encryption, decryption and verification is done by the GNUnet core and 
neither the application nor the transport code need to worry about it.");
 W("The format of the header that is added by the GNUnet core to each message 
is the following:");
-echo "<table class=\"border\" border=\"0\" cellspacing=\"0\" 
cellpadding=\"0\">\n";
-include("bittable.inc");
-fiveRowIntEntries("hash of the plaintext (RipeMD160)");
-rowIntEntryNBO("sequence number, 0 for plaintext");
-rowIntEntryNBO("timestamp (seconds), 0 for plaintext");
-rowIntEntryNBO("desired bandwidth (bytes per minute), 0 for plaintext");
-echo "</table>\n";
-P();
+EP();
+LAYOUT("P2P_Message",
+       F(ARRAY(N("hash of the plaintext (SHA-512)", "") => 64,
+               N("sequence number, 0 for plaintext", 11, NBO_()) => 4,
+               N("timestamp (in seconds)", NBO_()) => 4,
+               N("bandwidth limit (bytes per minute)", NBO_()) => 4)));
+BP();
 W("This header is followed by individual messages.");
-W("Note again that the identity of the sender must also be communicated, but 
how this is done depends on the specific transport.");
+W("Note again that the identity of the sender must also be communicated such 
that the core can select the right key for decryption.");
+W("However, how this is done depends on the specific transport.");
 
 EP();
 ANCHOR("HELO");H4("HELO");
@@ -116,27 +115,25 @@
 W("This is necessary because HELOs and %ss are needed to form the encrypted 
channel in the first place.",
   EXTLINK_("#SKEY","SKEY"));
 W("Once an encrypted channel was formed, nodes can exchange HELOs via that 
channel.");
-
-echo "<table class=\"border\" border=\"0\" cellspacing=\"0\" 
cellpadding=\"0\">\n";
-include("bittable.inc");
-rowSizeType("556 + " . W_("sender address size"),"0");
-rowIntEntryVerbatim(extlink_("doxygen/html/structSignature.html",
-                             "RSA signature (256 octets)"));
-row(shortEntryVerbatim_(extlink_("doxygen/html/structPublicKey.html","Public 
Key") .
-                       " " . W_("length of N + E + 2 (256+2+2 = 260)") . 
NBO_()),
-    shortEntryVerbatim_(W_("Public Key, length of N (256)") . NBO_()));
-rowIntEntry("Public Key, N (256 octets)");
-row(shortEntry_("Public Key, E"),
-    shortEntry_("padding (must be 0)"));
-fiveRowIntEntries("sender identity");
-rowIntEntryNBO("expiration time");
-rowIntEntryNBO("MTU");
-row(shortEntry_("sender address size (octets)", NBO_()),
-    shortEntry_("transport protocol number", NBO_()));
-rowIntEntryNBO("sender address (sender address size bytes)");
-echo "</table>\n";
 EP();
+LAYOUT("HELO_Message",
+       F(ARRAY(N("message size (600 + X)", NBO_()) => 2,
+              V("request type", 0, NBO_()) => 2,
+              N("RSA signature (signing data starting from sender id to end of 
HELO)","") => 256,
+              V("size of public key (T)", 264, NBO_()) => 2,
+              V("size of n in bytes (N)", 256, NBO_()) => 2,
+              N("n in public RSA key (N bytes)", "") => 256,
+              N("e in public RSA key (T - N bytes)", "") => 2,
+              V("padding", 0, NBO_()) => 2,
+              N("sender id (SHA-512 of data from T to padding)", "") => 64,
+              N("expiration time (in seconds)", NBO_()) => 4,
+              N("MTU of the transport (in bytes)", NBO_()) => 4,
+              N("sender address size (X, in bytes)", NBO_()) => 2,
+              N("transport protocol", NBO_()) => 2,
+              N("sender address", "") => 0)));
 
+
+
 ANCHOR("SKEY");H4("SKEY");
 BP();
 W("Sessionkeys are 128 bit keys for blowfish, a symmetric cipher that is used 
for all communication between GNUnet nodes except %ss and SKEYs themselves (for 
those, RSA with 2048 bit keys is used).",
@@ -162,21 +159,24 @@
   extlink_("#PONG","PONG"));
 W("The PONG must be encrypted and can be transmitted either as part of the 
symmetrically encrpyted portion of another SKEY or as an ordinary encrypted 
message.");
 P();
-W("The format of an %s is the following:",
-  extlink_("doxygen/html/structSKEY__Message.html","SKEY message"));
-P();
-
-echo "<table class=\"border\" border=\"0\" cellspacing=\"0\" 
cellpadding=\"0\">\n";
-include("bittable.inc");
-rowSizeType("520+N","1");
-rowIntEntryNBO("creation time (not expiration!)");
-rowIntEntry("RSA Encrypted data (256 octets)");
-rowIntEntry("Signature (256 octets)");
-rowIntEntry("N bytes symmetrically encrypted PING (and possibly PONG)");
-echo "</table>\n";
-W("Note that N is always either 28 or 56 bytes.");
-
+W("The format of an SKEY message is the following:");
 EP();
+LAYOUT("SKEY_Message",
+       F(ARRAY(N("message size (520 + X)", NBO_()) => 2,
+              V("request type", 1, NBO_()) => 2,
+              N("creation time (seconds)", NBO_()) => 4,
+              N("RSA encrypted data", "") => 256,
+              N("RSA signature", "") => 256,
+              N("AES-512 encrypted PINGs and PONGs", "") => 0)));
+BP();
+W("Note that X is always either 72 or 144 bytes.");
+W("The RSA encrypted data decrypts with the hostkey of the receiver to an 
AES-256 session key.");
+W("Using the RSA signature as the initialization vector, this key can be used 
to decrypt the PINGs and PONGs (if present).");
+W("The sessionkey is also used for all future communication with the peer 
(until HANGUP or timeout).");
+W("If PINGs are transmitted, the peer should respond by sending an encrypted 
PONG.");
+W("If the peer has not yet transmitted a session key, the PONG can be included 
in another SKEY message that is transmitted in response.");
+W("If a PONG is included, this should be verified and if it matches a prior 
PING used as confirmation that the other peer has received an earlier 
sessionkey.");
+EP();
 
 ANCHOR("PING");H4("PING");
 BP();
@@ -189,44 +189,36 @@
 P();
 W("The identity stored in the PING is the identity of the receiver.");
 W("If that identity does not match, the PING must be silently discarded.");
-
-echo "<table class=\"border\" border=\"0\" cellspacing=\"0\" 
cellpadding=\"0\">\n";
-include("bittable.inc");
-rowSizeType("28","2");
-fiveRowIntEntries("receiver identity");
-rowIntEntryNBO("challenge");
-echo "</table>\n";
 EP();
+LAYOUT("PINGPONG_Message",
+       F(ARRAY(V("message size", 72, NBO_()) => 2,
+              V("request type", 2, NBO_()) => 2,
+              N("challenge", NBO_()) => 4,
+              N("Identity of receiver of PING", "") => 64)));
 
+
 ANCHOR("PONG");H4("PONG");
 BP();
 W("PONGs are responses to PINGs.");
 W("If the node is not aware of a corresponding PING (or if the challenge is 
wrong), the PONG is silently dropped.");
 W("Otherwise the appropriate action corresponding to the PING is triggered.");
-
-echo "<table class=\"border\" border=\"0\" cellspacing=\"0\" 
cellpadding=\"0\">\n";
-include("bittable.inc");
-rowSizeType("28","3");
-fiveRowIntEntries("receiver identity");
-rowIntEntryNBO("challenge");
-echo "</table>\n";
 EP();
+LAYOUT("PINGPONG_Message",
+       F(ARRAY(V("message size", 72, NBO_()) => 2,
+              V("request type", 3, NBO_()) => 2,
+              N("challenge", NBO_()) => 4,
+              N("Identity of receiver of PING (sender for PONG)", "") => 64)));
 
 
 ANCHOR("HANGUP");H4("HANGUP");
 BP();
-W("The format of the HANGUP message is:");
-
-echo "<table class=\"border\" border=\"0\" cellspacing=\"0\" 
cellpadding=\"0\">\n";
-include("bittable.inc");
-rowSizeType("24","4");
-fiveRowIntEntries("sender identity");
-echo "</table>\n";
-
-BP();
 W("When a HANGUP message is received, the node must stop using the current 
sessionkey (assuming the receiver is the other node involved in the 
corresponding session with the sender).");
 W("If the receiving node desires further communication with the sender, a new 
sessionkey must be exchanged.");
-EP();
+W("The format of the HANGUP message is:");
+LAYOUT("HANGUP_Message",
+       F(ARRAY(V("message size", 68, NBO_()) => 2,
+              V("request type", 4, NBO_()) => 2,
+              N("Identity of sender", "") => 64)));
 
 
 ANCHOR("FRAGMENT");H4("FRAGMENT");
@@ -238,14 +230,14 @@
 W("The messages constructed from fragments cannot be larger than 64k.");
 W("The format for fragments is:");
 EP();
-echo "<table class=\"border\" border=\"0\" cellspacing=\"0\" 
cellpadding=\"0\">\n";
-include("bittable.inc");
-rowSizeType("12 + N","5");
-rowIntEntryNBO("fragment id");
-row(shortEntry_("offset"),
-    shortEntry_("total size"));
-rowIntEntry("N bytes of data");
-echo "</table>\n";
+
+LAYOUT("FRAGMENT_Message",
+       F(ARRAY(N("message size (12 + X)", NBO_()) => 2,
+              V("request type", 5, NBO_()) => 2,
+              N("fragment id", NBO_()) => 4,
+              N("offset", NBO_()) => 2,
+              N("total length of fragmented message", NBO_()) => 2,           
+              N("(size - 12) bytes of fragmented message at <tt>offset</tt>", 
"") => 0)));
 BP();
 W("The N bytes of data from the fragment belong to a larger message of the 
given total size and are to be placed at the given offset.");
 W("Unlike IP fragmentation, GNUnet fragments should never be overlapping.");
@@ -261,11 +253,10 @@
 W("Noise should only be used in encrypted traffic.");
 W("The format for noise is:");
 EP();
-echo "<table class=\"border\" border=\"0\" cellspacing=\"0\" 
cellpadding=\"0\">\n";
-include("bittable.inc");
-rowSizeType("&ge; 4","6");
-rowIntEntry("noise");
-echo "</table>\n";
+LAYOUT("p2p_HEADER",
+       F(ARRAY(N("message size", NBO_()) => 2,
+              V("request type", 6, NBO_()) => 2,
+              N("(size - 4) random bytes", "") => 0)));
 
 BP();
 W("The number of bytes of noise should be a multiple of 4 to preserve 
alignment.");

Modified: GNUnet-docs/WWW/todo
===================================================================
--- GNUnet-docs/WWW/todo        2005-07-13 15:21:33 UTC (rev 1465)
+++ GNUnet-docs/WWW/todo        2005-07-13 16:09:46 UTC (rev 1466)
@@ -1,4 +1,3 @@
 * update all transport protocol texts
 * update all P2P protocol texts
-* update traffic and fs CS protocol texts
 * update encoding text (describe what goes beyond ECRS!)