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

SAM:

Browse Source 
- 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)
This commit is contained in:
zzz
2014-07-19 15:57:32 +00:00
parent 3421d20a2f
commit 1d56d1a21e
3 changed files with 67 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
i2p2www/pages/site/docs/api/sam.html
View File

@ -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 %}
<p>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, <i>not</i> Base 64 encoded data.
To specify the Destination, you must use <a href="samv3>SAM V3</a>.
The DIRECTION can be specified for STREAM sessions, instructing
the bridge that the client will either be creating or receiving
streams, or both. If this is not specified, BOTH will be assumed.
@ -142,6 +145,12 @@ The RESULT value may be one of:
If it's not OK, the MESSAGE should contain human-readable information
as to why the session could not be created.
Note that there is no warning given if the $name is not found and
a transient destination is created instead.
Note that the actual transient destination is not output in the reply.
If you need these features, you must use <a href="samv3>SAM V3</a>.
----------------------------------------------------------------------
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: