From 1d56d1a21e6ba56a04bc0efc6bf33d26d4d03d20 Mon Sep 17 00:00:00 2001 From: zzz Date: Sat, 19 Jul 2014 15:57:32 +0000 Subject: [PATCH] SAM: - Document v1/v2 datagram modes in v3 (ticket #1334) - Clarify DESTINATION parameter in v1/v2 modes - Document minimum and recommended maximum datagram sizes (ticket #1335) --- i2p2www/pages/site/docs/api/sam.html | 23 ++++++++++++++---- i2p2www/pages/site/docs/api/samv2.html | 23 ++++++++++++++---- i2p2www/pages/site/docs/api/samv3.html | 32 +++++++++++++++++++++++--- 3 files changed, 67 insertions(+), 11 deletions(-) diff --git a/i2p2www/pages/site/docs/api/sam.html b/i2p2www/pages/site/docs/api/sam.html index 9fcea68d..eb4076d1 100644 --- a/i2p2www/pages/site/docs/api/sam.html +++ b/i2p2www/pages/site/docs/api/sam.html @@ -1,6 +1,6 @@ {% extends "global/layout.html" %} {% block title %}SAM V1 Specification{% endblock %} -{% block lastupdated %}June 2014{% endblock %} +{% block lastupdated %}July 2014{% endblock %} {% block accuratefor %}0.9.14{% endblock %} {% block content %}

Specified below is version 1 of a simple client protocol for interacting with @@ -103,11 +103,14 @@ follows: DESTINATION specifies what destination should be used for sending and receiving messages/streams. If a $name is given, the -SAM bridge looks through its own local storage for an associated +SAM bridge looks through its own local storage (the sam.keys file) for an associated destination (and private key). If no association exists matching that name, it creates a new one. If the destination is specified as TRANSIENT, it always creates a new one. +Note that DESTINATION is an identifier, not Base 64 encoded data. +To specify the Destination, you must use SAM V3. + + ---------------------------------------------------------------------- SAM virtual streams ---------------------------------------------------------------------- @@ -250,11 +259,14 @@ SAM repliable datagrams ---------------------------------------------------------------------- While I2P doesn't inherently contain a FROM address, for ease of use an additional layer is provided as repliable datagrams - unordered -and unreliable messages of up to 31KB in size that include a FROM +and unreliable messages of up to 31744 bytes that include a FROM address (leaving up to 1KB for header material). This FROM address is authenticated internally by SAM (making use of the destination's signing key to verify the source) and includes replay prevention. +Minimum size is 1. For best delivery reliability, recommended maximum +size is approximately 11 KB. + After establishing a SAM session with STYLE=DATAGRAM, the client can send the SAM bridge: @@ -279,7 +291,10 @@ SAM anonymous datagrams Squeezing the most out of I2P's bandwidth, SAM allows clients to send and receive anonymous datagrams, leaving authentication and reply information up to the client themselves. These datagrams are -unreliable and unordered, and may be up to 32KB in size. +unreliable and unordered, and may be up to 32768 bytes. + +Minimum size is 1. For best delivery reliability, recommended maximum +size is approximately 11 KB. After establishing a SAM session with STYLE=RAW, the client can send the SAM bridge: diff --git a/i2p2www/pages/site/docs/api/samv2.html b/i2p2www/pages/site/docs/api/samv2.html index e5c73477..10c57b8c 100644 --- a/i2p2www/pages/site/docs/api/samv2.html +++ b/i2p2www/pages/site/docs/api/samv2.html @@ -1,6 +1,6 @@ {% extends "global/layout.html" %} {% block title %}SAM V2 Specification{% endblock %} -{% block lastupdated %}June 2014{% endblock %} +{% block lastupdated %}July 2014{% endblock %} {% block accuratefor %}0.9.14{% endblock %} {% block content %}

Specified below is a simple client protocol for interacting with I2P. @@ -107,11 +107,14 @@ follows: DESTINATION specifies what destination should be used for sending and receiving messages/streams. If a $name is given, the -SAM bridge looks through its own local storage for an associated +SAM bridge looks through its own local storage (the sam.keys file) for an associated destination (and private key). If no association exists matching that name, it creates a new one. If the destination is specified as TRANSIENT, it always creates a new one. +Note that DESTINATION is an identifier, not Base 64 encoded data. +To specify the Destination, you must use SAM V3. + + ---------------------------------------------------------------------- SAM virtual streams ---------------------------------------------------------------------- @@ -307,11 +316,14 @@ SAM repliable datagrams ---------------------------------------------------------------------- While I2P doesn't inherently contain a FROM address, for ease of use an additional layer is provided as repliable datagrams - unordered -and unreliable messages of up to 31KB in size that include a FROM +and unreliable messages of up to 31744 bytes that include a FROM address (leaving up to 1KB for header material). This FROM address is authenticated internally by SAM (making use of the destination's signing key to verify the source) and includes replay prevention. +Minimum size is 1. For best delivery reliability, recommended maximum +size is approximately 11 KB. + After establishing a SAM session with STYLE=DATAGRAM, the client can send the SAM bridge: @@ -336,7 +348,10 @@ SAM anonymous datagrams Squeezing the most out of I2P's bandwidth, SAM allows clients to send and receive anonymous datagrams, leaving authentication and reply information up to the client themselves. These datagrams are -unreliable and unordered, and may be up to 32KB in size. +unreliable and unordered, and may be up to 32768 bytes. + +Minimum size is 1. For best delivery reliability, recommended maximum +size is approximately 11 KB. After establishing a SAM session with STYLE=RAW, the client can send the SAM bridge: diff --git a/i2p2www/pages/site/docs/api/samv3.html b/i2p2www/pages/site/docs/api/samv3.html index 6ab9cef2..619a35b9 100644 --- a/i2p2www/pages/site/docs/api/samv3.html +++ b/i2p2www/pages/site/docs/api/samv3.html @@ -1,6 +1,6 @@ {% extends "global/layout.html" %} {% block title %}SAM V3{% endblock %} -{% block lastupdated %}June 2014{% endblock %} +{% block lastupdated %}July 2014{% endblock %} {% block accuratefor %}0.9.14{% endblock %} {% block content %}

Specified below is a simple client protocol for interacting with I2P. @@ -46,6 +46,7 @@ Version 3.1 was introduced in I2P release 0.9.14.

  • DEST GENERATE and SESSION CREATE now support a SIGNATURE_TYPE parameter.
  • The MIN and MAX parameters in HELLO VERSION are now optional.
  • The MIN and MAX parameters in HELLO VERSION now support single-digit versions such as "3". +
  • RAW SEND is now supported on the bridge socket.

    @@ -352,11 +353,14 @@ SAM repliable datagrams : sending a datagram ---------------------------------------------------------------------- While I2P doesn't inherently contain a FROM address, for ease of use an additional layer is provided as repliable datagrams - unordered -and unreliable messages of up to 31KB in size that include a FROM +and unreliable messages of up to 31744 bytes that include a FROM address (leaving up to 1KB for header material). This FROM address is authenticated internally by SAM (making use of the destination's signing key to verify the source) and includes replay prevention. +Minimum size is 1. For best delivery reliability, recommended maximum +size is approximately 11 KB. + After establishing a SAM session with STYLE=DATAGRAM, the client can send datagrams through SAM's UDP port (7655). @@ -427,7 +431,10 @@ SAM anonymous datagrams Squeezing the most out of I2P's bandwidth, SAM allows clients to send and receive anonymous datagrams, leaving authentication and reply information up to the client themselves. These datagrams are -unreliable and unordered, and may be up to 32KB in size. +unreliable and unordered, and may be up to 32768 bytes. + +Minimum size is 1. For best delivery reliability, recommended maximum +size is approximately 11 KB. After establishing a SAM session with STYLE=RAW, the client can send anonymous datagrams through the SAM bridge exactly the same way @@ -449,6 +456,25 @@ the following data : {$datagram_payload} +---------------------------------------------------------------------- +V1/V2 Compatible Datagram Handling +---------------------------------------------------------------------- + +In SAM V3, the preferred way to send datagrams is via the datagram socket +at port 7655 as documented above. However, repliable datagrams may be sent +directly via the SAM bridge socket using the DATAGRAM SEND command, +as documented in SAM V2. + +As of release 0.9.14 (version 3.1), anonymous datagrams may be sent +directly via the SAM bridge socket using the RAW SEND command, +as documented in SAM V2. + +These commands do not support the ID parameter. The datagrams are +sent to the most recently created DATAGRAM- or RAW-style session, +as appropriate. Support for the ID parameter may be added in a future release. + + + ---------------------------------------------------------------------- SAM utility functionality ----------------------------------------------------------------------