SAM:
- More consistency in key/value syntax some changes taken from ticket #1488 patch 0001 - Clarify destination and private key everywhere - Clarify key=value quoting and lack of escaping (ticket #1488) - Add more v3 references to DATAGRAM SEND and RAW SEND (ticket #1488 comment 7) - More links - HTML-ize the v3 spec
This commit is contained in:
@ -1,7 +1,7 @@
|
||||
{% extends "global/layout.html" %}
|
||||
{% block title %}SAM V1 Specification{% endblock %}
|
||||
{% block lastupdated %}September 2014{% endblock %}
|
||||
{% block accuratefor %}0.9.15{% endblock %}
|
||||
{% block lastupdated %}May 2015{% endblock %}
|
||||
{% block accuratefor %}0.9.20{% endblock %}
|
||||
{% block content %}
|
||||
<p>Specified below is version 1 of a simple client protocol for interacting with
|
||||
I2P.
|
||||
@ -54,6 +54,10 @@ the key=value pairs can change (e.g. "ONE TWO A=B C=D" or
|
||||
"ONE TWO C=D A=B" are both perfectly valid constructions). In
|
||||
addition, the protocol is case-sensitive.
|
||||
|
||||
SAM messages are interpreted in UTF-8. Key=value pairs must be separated by
|
||||
a single space. Values may be enclosed in double quotes if they contain spaces,
|
||||
e.g. key="long value text". There is no escaping mechanism.
|
||||
|
||||
Communication can take three distinct forms:
|
||||
* <a href="{{ site_url('docs/api/streaming') }}">Virtual streams</a>
|
||||
* <a href="{{ site_url('docs/spec/datagrams') }}#repliable">Repliable datagrams</a> (messages with a FROM field)
|
||||
@ -164,11 +168,16 @@ forth to manage the streams, as listed below:
|
||||
|
||||
STREAM CONNECT
|
||||
ID=$id
|
||||
DESTINATION=$base64key
|
||||
DESTINATION=$destination
|
||||
|
||||
This establishes a new virtual connection from the local destination
|
||||
to the specified peer, marking it with the session-scoped unique ID.
|
||||
The unique ID is an ASCII base 10 integer from 1 through (2^31-1).
|
||||
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
The SAM bridge must reply to this with a stream status message:
|
||||
|
||||
STREAM STATUS
|
||||
@ -193,7 +202,7 @@ On the receiving end, the SAM bridge simply notifies the client as
|
||||
follows:
|
||||
|
||||
STREAM CONNECTED
|
||||
DESTINATION=$base64key
|
||||
DESTINATION=$destination
|
||||
ID=$id
|
||||
|
||||
This tells the client that the given destination has created a virtual
|
||||
@ -201,6 +210,10 @@ connection with them. The following data stream will be marked with
|
||||
the given unique ID, that is an ASCII base 10 integer from -1 through
|
||||
-(2^31-1).
|
||||
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
When the client wants to send data on the virtual connection, they
|
||||
do so as follows:
|
||||
|
||||
@ -272,15 +285,19 @@ After establishing a SAM session with STYLE=DATAGRAM, the client can
|
||||
send the SAM bridge:
|
||||
|
||||
DATAGRAM SEND
|
||||
DESTINATION=$base64key
|
||||
DESTINATION=$destination
|
||||
SIZE=$numBytes\n[$numBytes of data]
|
||||
|
||||
When a datagram arrives, the bridge delivers it to the client via:
|
||||
|
||||
DATAGRAM RECEIVED
|
||||
DESTINATION=$base64key
|
||||
DESTINATION=$destination
|
||||
SIZE=$numBytes\n[$numBytes of data]
|
||||
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
The SAM bridge never exposes to the client the authentication headers
|
||||
or other fields, merely the data that the sender provided. This
|
||||
continues until the session is closed (by the client dropping the
|
||||
@ -301,9 +318,13 @@ After establishing a SAM session with STYLE=RAW, the client can
|
||||
send the SAM bridge:
|
||||
|
||||
RAW SEND
|
||||
DESTINATION=$base64key
|
||||
DESTINATION=$destination
|
||||
SIZE=$numBytes\n[$numBytes of data]
|
||||
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
When a raw datagram arrives, the bridge delivers it to the client
|
||||
via:
|
||||
|
||||
@ -324,7 +345,7 @@ which is answered by
|
||||
NAMING REPLY
|
||||
RESULT=$result
|
||||
NAME=$name
|
||||
[VALUE=$base64key]
|
||||
[VALUE=$destination]
|
||||
[MESSAGE=$message]
|
||||
|
||||
|
||||
@ -334,11 +355,15 @@ The RESULT value may be one of:
|
||||
INVALID_KEY
|
||||
KEY_NOT_FOUND
|
||||
|
||||
If NAME=ME, then the reply will contain the base64key used by the
|
||||
If NAME=ME, then the reply will contain the destination used by the
|
||||
current session (useful if you're using a TRANSIENT one). If $result
|
||||
is not OK, MESSAGE may convey a descriptive message, such as "bad
|
||||
format", etc.
|
||||
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
Public and private base64 keys can be generated using the following
|
||||
message:
|
||||
|
||||
@ -347,7 +372,7 @@ message:
|
||||
which is answered by
|
||||
|
||||
DEST REPLY
|
||||
PUB=$pubkey
|
||||
PUB=$destination
|
||||
PRIV=$privkey
|
||||
|
||||
As of I2P 0.9.14, an optional parameter SIGNATURE_TYPE is supported.
|
||||
@ -355,6 +380,17 @@ The SIGNATURE_TYPE value may be any name (e.g. ECDSA_SHA256_P256, case insensiti
|
||||
that is supported by <a href="{{ site_url('docs/spec/common-structures') }}#type_Certificate">Key Certificates</a>.
|
||||
The default is DSA_SHA1.
|
||||
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
The $privkey is the base 64 of the concatenation of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>
|
||||
followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_PrivateKey">Private Key</a>
|
||||
followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_SigningPrivateKey">Signing Private Key</a>,
|
||||
which is 884 or more base 64 characters (663 or more bytes in binary),
|
||||
depending on signature type.
|
||||
The binary format is specified in <a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/PrivateKeyFile.html">Private Key File</a>.
|
||||
|
||||
----------------------------------------------------------------------
|
||||
RESULT values
|
||||
----------------------------------------------------------------------
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
{% extends "global/layout.html" %}
|
||||
{% block title %}SAM V2 Specification{% endblock %}
|
||||
{% block lastupdated %}September 2014{% endblock %}
|
||||
{% block accuratefor %}0.9.15{% endblock %}
|
||||
{% block lastupdated %}May 2015{% endblock %}
|
||||
{% block accuratefor %}0.9.20{% endblock %}
|
||||
{% block content %}
|
||||
<p>Specified below is a simple client protocol for interacting with I2P.
|
||||
</p>
|
||||
@ -58,6 +58,10 @@ the key=value pairs can change (e.g. "ONE TWO A=B C=D" or
|
||||
"ONE TWO C=D A=B" are both perfectly valid constructions). In
|
||||
addition, the protocol is case-sensitive.
|
||||
|
||||
SAM messages are interpreted in UTF-8. Key=value pairs must be separated by
|
||||
a single space. Values may be enclosed in double quotes if they contain spaces,
|
||||
e.g. key="long value text". There is no escaping mechanism.
|
||||
|
||||
Communication can take three distinct forms:
|
||||
* <a href="{{ site_url('docs/api/streaming') }}">Virtual streams</a>
|
||||
* <a href="{{ site_url('docs/spec/datagrams') }}#repliable">Repliable datagrams</a> (messages with a FROM field)
|
||||
@ -168,11 +172,15 @@ forth to manage the streams, as listed below:
|
||||
|
||||
STREAM CONNECT
|
||||
ID=$id
|
||||
DESTINATION=$base64key
|
||||
DESTINATION=$destination
|
||||
|
||||
This establishes a new virtual connection from the local destination
|
||||
to the specified peer, marking it with the session-scoped unique ID.
|
||||
The unique ID is an ASCII base 10 integer from 1 through (2^31-1).
|
||||
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
The SAM bridge replies to this with a stream status message:
|
||||
|
||||
STREAM STATUS
|
||||
@ -197,7 +205,7 @@ On the receiving end, the SAM bridge simply notifies the client as
|
||||
follows:
|
||||
|
||||
STREAM CONNECTED
|
||||
DESTINATION=$base64key
|
||||
DESTINATION=$destination
|
||||
ID=$id
|
||||
|
||||
This tells the client that the given destination has created a virtual
|
||||
@ -205,6 +213,10 @@ connection with them. The following data stream will be marked with
|
||||
the given unique ID, that is an ASCII base 10 integer from -1 through
|
||||
-(2^31-1).
|
||||
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
When the client wants to send data on the virtual connection, they
|
||||
do so as follows:
|
||||
|
||||
@ -329,15 +341,19 @@ After establishing a SAM session with STYLE=DATAGRAM, the client can
|
||||
send the SAM bridge:
|
||||
|
||||
DATAGRAM SEND
|
||||
DESTINATION=$base64key
|
||||
DESTINATION=$destination
|
||||
SIZE=$numBytes\n[$numBytes of data]
|
||||
|
||||
When a datagram arrives, the bridge delivers it to the client via:
|
||||
|
||||
DATAGRAM RECEIVED
|
||||
DESTINATION=$base64key
|
||||
DESTINATION=$destination
|
||||
SIZE=$numBytes\n[$numBytes of data]
|
||||
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
The SAM bridge never exposes to the client the authentication headers
|
||||
or other fields, merely the data that the sender provided. This
|
||||
continues until the session is closed (by the client dropping the
|
||||
@ -358,9 +374,13 @@ After establishing a SAM session with STYLE=RAW, the client can
|
||||
send the SAM bridge:
|
||||
|
||||
RAW SEND
|
||||
DESTINATION=$base64key
|
||||
DESTINATION=$destination
|
||||
SIZE=$numBytes\n[$numBytes of data]
|
||||
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
When a raw datagram arrives, the bridge delivers it to the client
|
||||
via:
|
||||
|
||||
@ -381,7 +401,7 @@ which is answered by
|
||||
NAMING REPLY
|
||||
RESULT=$result
|
||||
NAME=$name
|
||||
[VALUE=$base64key]
|
||||
[VALUE=$destination]
|
||||
[MESSAGE=$message]
|
||||
|
||||
|
||||
@ -391,11 +411,16 @@ The RESULT value may be one of:
|
||||
INVALID_KEY
|
||||
KEY_NOT_FOUND
|
||||
|
||||
If NAME=ME, then the reply will contain the base64key used by the
|
||||
If NAME=ME, then the reply will contain the destnation used by the
|
||||
current session (useful if you're using a TRANSIENT one). If $result
|
||||
is not OK, MESSAGE may convey a descriptive message, such as "bad
|
||||
format", etc.
|
||||
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
|
||||
Public and private base64 keys can be generated using the following
|
||||
message:
|
||||
|
||||
@ -404,7 +429,7 @@ message:
|
||||
which is answered by
|
||||
|
||||
DEST REPLY
|
||||
PUB=$pubkey
|
||||
PUB=$destination
|
||||
PRIV=$privkey
|
||||
|
||||
As of I2P 0.9.14, an optional parameter SIGNATURE_TYPE is supported.
|
||||
@ -412,6 +437,17 @@ The SIGNATURE_TYPE value may be any name (e.g. ECDSA_SHA256_P256, case insensiti
|
||||
that is supported by <a href="{{ site_url('docs/spec/common-structures') }}#type_Certificate">Key Certificates</a>.
|
||||
The default is DSA_SHA1.
|
||||
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
The $privkey is the base 64 of the concatenation of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>
|
||||
followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_PrivateKey">Private Key</a>
|
||||
followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_SigningPrivateKey">Signing Private Key</a>,
|
||||
which is 884 or more base 64 characters (663 or more bytes in binary),
|
||||
depending on signature type.
|
||||
The binary format is specified in <a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/PrivateKeyFile.html">Private Key File</a>.
|
||||
|
||||
----------------------------------------------------------------------
|
||||
RESULT values
|
||||
----------------------------------------------------------------------
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
{% extends "global/layout.html" %}
|
||||
{% block title %}SAM V3{% endblock %}
|
||||
{% block lastupdated %}July 2014{% endblock %}
|
||||
{% block accuratefor %}0.9.14{% endblock %}
|
||||
{% block lastupdated %}May 2015{% endblock %}
|
||||
{% block accuratefor %}0.9.20{% endblock %}
|
||||
{% block content %}
|
||||
<p>Specified below is a simple client protocol for interacting with I2P.
|
||||
</p>
|
||||
@ -52,20 +52,20 @@ Version 3.1 was introduced in I2P release 0.9.14.
|
||||
</p>
|
||||
|
||||
<h2>Version 3 Protocol</h2>
|
||||
<pre>
|
||||
----------------------------------------------------------------------
|
||||
Simple Anonymous Messaging (SAM version 3.0) Specification
|
||||
----------------------------------------------------------------------
|
||||
<h3>Simple Anonymous Messaging (SAM version 3.0) Specification Overview</h3>
|
||||
<p>
|
||||
Client application talks to SAM bridge, which deals with
|
||||
all of the I2P functionality (using the streaming
|
||||
lib for virtual streams, or I2CP directly for async messages).
|
||||
|
||||
</p><p>
|
||||
All client<-->SAM bridge communication is unencrypted and
|
||||
unauthenticated. Access to the SAM
|
||||
bridge should be protected through firewalls or other means
|
||||
(perhaps the bridge may have ACLs on what IPs it accepts
|
||||
connections from).
|
||||
|
||||
</p><p>
|
||||
All of these SAM messages are sent on a single line in plain ASCII,
|
||||
terminated by the newline character (\n). The formatting shown
|
||||
below is merely for readability, and while the first two words in
|
||||
@ -77,70 +77,96 @@ In the following, message examples are preceded by "-> " for
|
||||
messages sent by the client to the SAM bridge, and by "<- " for
|
||||
messages sent by the SAM bridge to the client.
|
||||
|
||||
I2P communications can take three distinct forms:
|
||||
* <a href="{{ site_url('docs/api/streaming') }}">Virtual streams</a>
|
||||
* <a href="{{ site_url('docs/spec/datagrams') }}#repliable">Repliable datagrams</a> (messages with a FROM field)
|
||||
* <a href="{{ site_url('docs/spec/datagrams') }}#raw">Anonymous datagrams</a> (raw anonymous messages)
|
||||
</p><p>
|
||||
SAM messages are interpreted in UTF-8. Key=value pairs must be separated by
|
||||
a single space. Values may be enclosed in double quotes if they contain spaces,
|
||||
e.g. key="long value text". There is no escaping mechanism.
|
||||
|
||||
</p><p>
|
||||
I2P communications can take three distinct forms:
|
||||
<ul><li>
|
||||
<a href="{{ site_url('docs/api/streaming') }}">Virtual streams</a>
|
||||
</lil><li>
|
||||
<a href="{{ site_url('docs/spec/datagrams') }}#repliable">Repliable datagrams</a> (messages with a FROM field)
|
||||
</lil><li>
|
||||
<a href="{{ site_url('docs/spec/datagrams') }}#raw">Anonymous datagrams</a> (raw anonymous messages)
|
||||
</lil></ul>
|
||||
</p><p>
|
||||
I2P communications are supported by I2P sessions, and each I2P
|
||||
session is bound to an address (called destination). An I2P session
|
||||
is associated with one of the three types above, and cannot carry
|
||||
communications of another type.
|
||||
|
||||
</p>
|
||||
|
||||
----------------------------------------------------------------------
|
||||
SAM connection handshake
|
||||
----------------------------------------------------------------------
|
||||
<h3>SAM connection handshake</h3>
|
||||
<p>
|
||||
No SAM communication can occur until after the client and bridge have
|
||||
agreed on a protocol version, which is done by the client sending
|
||||
a HELLO and the bridge sending a HELLO REPLY:
|
||||
|
||||
<pre>
|
||||
-> HELLO VERSION MIN=$min MAX=$max
|
||||
|
||||
</pre>
|
||||
and
|
||||
|
||||
<pre>
|
||||
<- HELLO REPLY RESULT=OK VERSION=3.1
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
As of version 3.1 (I2P 0.9.14), the MIN and MAX parameters are optional.
|
||||
SAM will always return the highest version possible given the
|
||||
MIN and MAX constraints, or 3.1 if no constraints are given.
|
||||
|
||||
If the SAM bridge cannot find a suitable version, it replies with :
|
||||
|
||||
<pre>
|
||||
<- HELLO REPLY RESULT=NOVERSION
|
||||
|
||||
</pre>
|
||||
If some error occurred, such as a bad request format, it replies with :
|
||||
<pre>
|
||||
<- HELLO REPLY RESULT=I2P_ERROR MESSAGE=$message
|
||||
</pre>
|
||||
</p>
|
||||
|
||||
<- HELLO REPLY RESULT=I2P_ERROR MESSAGE={$message}
|
||||
|
||||
|
||||
----------------------------------------------------------------------
|
||||
SAM sessions
|
||||
----------------------------------------------------------------------
|
||||
<h3>SAM sessions</h3>
|
||||
<p>
|
||||
A SAM session is created by a client opening a socket to the SAM
|
||||
bridge, operating a handshake, and sending a SESSION CREATE message,
|
||||
and the session terminates when the socket is disconnected.
|
||||
|
||||
</p><p>
|
||||
Each registered I2P Destination is uniquely associated with a session ID
|
||||
(or nickname).
|
||||
|
||||
</p><p>
|
||||
Each session is uniquely associated with :
|
||||
* the socket from which the client creates the session
|
||||
* its ID (or nickname)
|
||||
<ul><li>
|
||||
the socket from which the client creates the session
|
||||
</li><li>
|
||||
its ID (or nickname)
|
||||
</li></ul>
|
||||
|
||||
</p><p>
|
||||
The session creation message can only use one of these forms (messages
|
||||
received through other forms are answered with an error message) :
|
||||
|
||||
<pre>
|
||||
-> SESSION CREATE
|
||||
STYLE={STREAM,DATAGRAM,RAW}
|
||||
ID={$nickname}
|
||||
DESTINATION={$private_destination_key,TRANSIENT}
|
||||
ID=$nickname
|
||||
DESTINATION={$privkey,TRANSIENT}
|
||||
[option=value]*
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
DESTINATION specifies what destination should be used for
|
||||
sending and receiving messages/streams. It is the base 64 encoding of
|
||||
the concatenation of the destination, private key, and signing private key.
|
||||
sending and receiving messages/streams.
|
||||
The $privkey is the base 64 of the concatenation of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>
|
||||
followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_PrivateKey">Private Key</a>
|
||||
followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_SigningPrivateKey">Signing Private Key</a>,
|
||||
which is 663 or more bytes in binary and 884 or more bytes in base 64,
|
||||
depending on signature type.
|
||||
The binary format is specified in <a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/PrivateKeyFile.html">Private Key File</a>.
|
||||
|
||||
</p><p>
|
||||
If the destination is specified as TRANSIENT, the SAM bridge creates a new destination.
|
||||
As of version 3.1 (I2P 0.9.14), if the destination is TRANSIENT, an optional parameter
|
||||
SIGNATURE_TYPE is supported. The SIGNATURE_TYPE value may be any name
|
||||
@ -148,193 +174,277 @@ SIGNATURE_TYPE is supported. The SIGNATURE_TYPE value may be any name
|
||||
supported by <a href="{{ site_url('docs/spec/common-structures') }}#type_Certificate">Key Certificates</a>.
|
||||
The default is DSA_SHA1.
|
||||
|
||||
{$nickname} is the choice of the client. No whitespace is allowed.
|
||||
</p><p>
|
||||
$nickname is the choice of the client. No whitespace is allowed.
|
||||
|
||||
</p><p>
|
||||
Additional options given are passed to the I2P session
|
||||
configuration if not interpreted by the SAM bridge (e.g.
|
||||
outbound.length=0). These options are documented below.
|
||||
outbound.length=0). These options <a href="#options">are documented below</a>..
|
||||
|
||||
</p><p>
|
||||
The SAM bridge itself should already be configured with what router
|
||||
it should communicate over I2P through (though if need be there may
|
||||
be a way to provide an override, e.g. i2cp.tcp.host=localhost and
|
||||
i2cp.tcp.port=7654).
|
||||
|
||||
</p><p>
|
||||
After receiving the session create message, the SAM bridge will reply
|
||||
with a session status message, as follows:
|
||||
|
||||
</p><p>
|
||||
If the creation was successful :
|
||||
<- SESSION STATUS RESULT=OK DESTINATION={$private_destination_key}
|
||||
<pre>
|
||||
<- SESSION STATUS RESULT=OK DESTINATION=$privkey
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
The $privkey is the base 64 of the concatenation of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>
|
||||
followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_PrivateKey">Private Key</a>
|
||||
followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_SigningPrivateKey">Signing Private Key</a>,
|
||||
which is 663 or more bytes in binary and 884 or more bytes in base 64,
|
||||
depending on signature type.
|
||||
The binary format is specified in <a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/PrivateKeyFile.html">Private Key File</a>.
|
||||
|
||||
</p><p>
|
||||
If the nickname is already associated with a session :
|
||||
<pre>
|
||||
<- SESSION STATUS RESULT=DUPLICATED_ID
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
If the destination is already in use :
|
||||
<pre>
|
||||
<- SESSION STATUS RESULT=DUPLICATED_DEST
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
If the destination is not a valid private destination key :
|
||||
<pre>
|
||||
<- SESSION STATUS RESULT=INVALID_KEY
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
If some other error has occurred :
|
||||
<- SESSION STATUS RESULT=I2P_ERROR MESSAGE={$message}
|
||||
<pre>
|
||||
<- SESSION STATUS RESULT=I2P_ERROR MESSAGE=$message
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
If it's not OK, the MESSAGE should contain human-readable information
|
||||
as to why the session could not be created.
|
||||
|
||||
|
||||
</p><p>
|
||||
SAM sessions live and die with the socket they are associated with.
|
||||
When the socket is closed, the session dies, and all communications
|
||||
using the session die at the same time. And the other way round, when
|
||||
the session dies for any reason, the SAM bridge closes the socket.
|
||||
</p>
|
||||
|
||||
|
||||
----------------------------------------------------------------------
|
||||
SAM virtual streams
|
||||
----------------------------------------------------------------------
|
||||
<h3>SAM virtual streams</h3>
|
||||
<p>
|
||||
Virtual streams are guaranteed to be sent reliably and in order, with
|
||||
failure and success notification as soon as it is available.
|
||||
|
||||
</p><p>
|
||||
Streams are bidirectional communication sockets between two I2P
|
||||
destinations, but their opening has to be requested by one of them.
|
||||
Hereafter, CONNECT commands are used by the SAM client for such a
|
||||
request. FORWARD / ACCEPT commands are used by the SAM client when
|
||||
he wants to listen to requests coming from other I2P destinations.
|
||||
</p>
|
||||
|
||||
|
||||
-----------------------------
|
||||
SAM virtual streams : CONNECT
|
||||
-----------------------------
|
||||
<h3>SAM virtual streams : CONNECT</h3>
|
||||
<p>
|
||||
A client asks for a connection by :
|
||||
* opening a new socket with the SAM bridge
|
||||
* passing the same HELLO handshake as above
|
||||
* sending the connection command :
|
||||
<ul><li>
|
||||
opening a new socket with the SAM bridge
|
||||
</li><li>
|
||||
passing the same HELLO handshake as above
|
||||
</li><li>
|
||||
sending the connection command :
|
||||
</li></ul>
|
||||
|
||||
<pre>
|
||||
-> STREAM CONNECT
|
||||
ID={$nickname}
|
||||
DESTINATION=$peer_public_base64_key
|
||||
ID=$nickname
|
||||
DESTINATION=$destination
|
||||
[SILENT={true,false}]
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
This establishes a new virtual connection from the local session
|
||||
whose ID is {$nickname} to the specified peer.
|
||||
whose ID is $nickname to the specified peer.
|
||||
|
||||
</p><p>
|
||||
The target is $destination, which is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
</p><p>
|
||||
If SILENT=true is passed, the SAM bridge won't issue any other message
|
||||
on the socket : if the connection fails, the socket will be closed.
|
||||
If the connection succeeds, all remaining data passing through the
|
||||
current socket is forwarded from and to the connected I2P destination
|
||||
peer.
|
||||
|
||||
</p><p>
|
||||
If SILENT=false, which is the default value, the SAM bridge sends a
|
||||
last message to its client before forwarding or shutting down the
|
||||
socket :
|
||||
|
||||
<pre>
|
||||
<- STREAM STATUS
|
||||
RESULT=$result
|
||||
[MESSAGE=...]
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
The RESULT value may be one of:
|
||||
|
||||
<pre>
|
||||
OK
|
||||
CANT_REACH_PEER
|
||||
I2P_ERROR
|
||||
INVALID_KEY
|
||||
INVALID_ID
|
||||
TIMEOUT
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
If the RESULT is OK, all remaining data passing through the
|
||||
current socket is forwarded from and to the connected I2P destination
|
||||
peer. If the connection was not possible (timeout, etc),
|
||||
RESULT will contain the appropriate error value (accompanied by an
|
||||
optional human-readable MESSAGE), and the SAM bridge closes the
|
||||
socket.
|
||||
</p>
|
||||
|
||||
----------------------------
|
||||
SAM virtual streams : ACCEPT
|
||||
----------------------------
|
||||
|
||||
<h3>SAM virtual streams : ACCEPT</h3>
|
||||
<p>
|
||||
A client waits for an incoming connection request by :
|
||||
* opening a new socket with the SAM bridge
|
||||
* passing the same HELLO handshake as above
|
||||
* sending the accept command :
|
||||
<ul><li>
|
||||
opening a new socket with the SAM bridge
|
||||
</li><li>
|
||||
passing the same HELLO handshake as above
|
||||
</li><li>
|
||||
sending the accept command :
|
||||
</li></ul>
|
||||
|
||||
<pre>
|
||||
-> STREAM ACCEPT
|
||||
ID={$nickname}
|
||||
ID=$nickname
|
||||
[SILENT={true,false}]
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
This makes the session ${nickname} listen for one incoming
|
||||
connection request from the I2P network.
|
||||
|
||||
</p><p>
|
||||
The SAM bridge answers with :
|
||||
|
||||
<pre>
|
||||
<- STREAM STATUS
|
||||
RESULT=$result
|
||||
[MESSAGE=...]
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
The RESULT value may be one of:
|
||||
|
||||
<pre>
|
||||
OK
|
||||
I2P_ERROR
|
||||
INVALID_ID
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
If the result is not OK, the socket is closed immediately by the SAM
|
||||
bridge. If the result is OK, the SAM bridge starts waiting for an
|
||||
incoming connection request from another I2P peer. When a request
|
||||
arrives, the SAM bridge accepts it and :
|
||||
|
||||
* If SILENT=true was passed, the SAM bridge won't issue any other message
|
||||
</p><p>
|
||||
If SILENT=true was passed, the SAM bridge won't issue any other message
|
||||
on the client socket : all remaining data passing through the
|
||||
current socket is forwarded from and to the connected I2P destination
|
||||
peer.
|
||||
* If SILENT=false was passed, which is the default value, the SAM bridge
|
||||
|
||||
</p><p>
|
||||
If SILENT=false was passed, which is the default value, the SAM bridge
|
||||
sends the client a ASCII line containing the base64 public destination key
|
||||
of the requesting peer. After this '\n' terminated line, all remaining data
|
||||
passing through the current socket is forwarded from and to the connected
|
||||
I2P destination peer, until one of the peer closes the socket.
|
||||
</p>
|
||||
|
||||
-----------------------------
|
||||
SAM virtual streams : FORWARD
|
||||
-----------------------------
|
||||
|
||||
<h3>SAM virtual streams : FORWARD</h3>
|
||||
<p>
|
||||
A client can use a regular socket server and wait for connection requests
|
||||
coming from I2P. For that, the client has to :
|
||||
* open a new socket with the SAM bridge
|
||||
* pass the same HELLO handshake as above
|
||||
* send the forward command :
|
||||
<ul><li>
|
||||
open a new socket with the SAM bridge
|
||||
</li><li>
|
||||
pass the same HELLO handshake as above
|
||||
</li><li>
|
||||
send the forward command :
|
||||
</ul><li>
|
||||
|
||||
<pre>
|
||||
-> STREAM FORWARD
|
||||
ID={$nickname}
|
||||
PORT={$port}
|
||||
[HOST={$host}]
|
||||
ID=$nickname
|
||||
PORT=$port
|
||||
[HOST=$host]
|
||||
[SILENT={true,false}]
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
This makes the session ${nickname} listen for incoming
|
||||
connection requests from the I2P network.
|
||||
|
||||
</p><p>
|
||||
The SAM bridge answers with :
|
||||
|
||||
<pre>
|
||||
<- STREAM STATUS
|
||||
RESULT=$result
|
||||
[MESSAGE=...]
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
The RESULT value may be one of:
|
||||
|
||||
<pre>
|
||||
OK
|
||||
I2P_ERROR
|
||||
INVALID_ID
|
||||
</pre>
|
||||
|
||||
* {$host} is the hostname or IP address of the socket server to which
|
||||
</p><p>
|
||||
$host is the hostname or IP address of the socket server to which
|
||||
SAM will forward connection requests. If not given, SAM takes the IP
|
||||
of the socket that issued the forward command.
|
||||
|
||||
* {$port} is the port number of the socket server to which SAM will
|
||||
</p><p>
|
||||
$port is the port number of the socket server to which SAM will
|
||||
forward connection requests. It is mandatory.
|
||||
|
||||
</p><p>
|
||||
When a connection request arrives from I2P, the SAM bridge requests a
|
||||
socket connection from {$host}:{$port}. If it is accepted after no more
|
||||
socket connection from $host:$port. If it is accepted after no more
|
||||
than 3 seconds, SAM will accept the connection from I2P, and then :
|
||||
|
||||
* If SILENT=true was passed, all data passing through the obtained
|
||||
</p><p>
|
||||
If SILENT=true was passed, all data passing through the obtained
|
||||
current socket is forwarded from and to the connected I2P destination
|
||||
peer.
|
||||
* If SILENT=false was passed, which is the default value, the SAM bridge
|
||||
|
||||
</p><p>
|
||||
If SILENT=false was passed, which is the default value, the SAM bridge
|
||||
sends on the obtained socket an ASCII line containing the base64 public
|
||||
destination key of the requesting peer. After this '\n' terminated line,
|
||||
all remaining data passing through the socket is forwarded from and to
|
||||
@ -343,15 +453,15 @@ socket.
|
||||
|
||||
|
||||
|
||||
</p><p>
|
||||
The I2P router will stop listening to incoming connection requests as
|
||||
soon as the "forwarding" socket is closed.
|
||||
|
||||
|
||||
|
||||
|
||||
----------------------------------------------------------------------
|
||||
SAM repliable datagrams : sending a datagram
|
||||
----------------------------------------------------------------------
|
||||
<h3>SAM repliable datagrams : sending a datagram</h3>
|
||||
<p>
|
||||
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 31744 bytes that include a FROM
|
||||
@ -359,174 +469,262 @@ 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.
|
||||
|
||||
</p><p>
|
||||
Minimum size is 1. For best delivery reliability, recommended maximum
|
||||
size is approximately 11 KB.
|
||||
|
||||
</p><p>
|
||||
After establishing a SAM session with STYLE=DATAGRAM, the client can
|
||||
send datagrams through SAM's UDP port (7655).
|
||||
|
||||
</p><p>
|
||||
The first line of a datagram sent through this port has to be in the
|
||||
following format :
|
||||
|
||||
3.0 {$nickname} {$base64_public_destination_key}
|
||||
<p>
|
||||
3.0 $nickname $destination
|
||||
</p>
|
||||
|
||||
* 3.0 is the version of SAM
|
||||
* {$nickname} is the id of the DGRAM session that will be used
|
||||
* {$base64_public_destination_key} is the destination of the
|
||||
datagram
|
||||
* this line is '\n' terminated.
|
||||
<ul><li>
|
||||
3.0 is the version of SAM
|
||||
</li><li>
|
||||
$nickname is the id of the DGRAM session that will be used
|
||||
</li><li>
|
||||
The target is $destination, which is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
</li><li>
|
||||
this line is '\n' terminated.
|
||||
</li></ul>
|
||||
|
||||
</p><p>
|
||||
The first line will be discarded by SAM before sending the remaining
|
||||
of the message to the specified destination.
|
||||
|
||||
----------------------------------------------------------------------
|
||||
SAM repliable datagrams : receiving a datagram
|
||||
----------------------------------------------------------------------
|
||||
</p><p>
|
||||
For an alternate method of sending repliable datagrams, see <a href="#dgsend">DATAGRAM SEND</a>.
|
||||
</p>
|
||||
|
||||
<h3>SAM repliable datagrams : receiving a datagram</h3>
|
||||
<p>
|
||||
Received datagrams are written by SAM on the socket from which the
|
||||
datagram session was opened, unless specified otherwise by the CREATE
|
||||
command.
|
||||
|
||||
</p><p>
|
||||
When a datagram arrives, the bridge delivers it to the client via the
|
||||
message :
|
||||
|
||||
<pre>
|
||||
<- DATAGRAM RECEIVED
|
||||
DESTINATION=$base64key
|
||||
DESTINATION=$destination
|
||||
SIZE=$numBytes\n[$numBytes of data]
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
The source is $destination, which is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
</p><p>
|
||||
The SAM bridge never exposes to the client the authentication headers
|
||||
or other fields, merely the data that the sender provided. This
|
||||
continues until the session is closed (by the client dropping the
|
||||
connection).
|
||||
|
||||
----------------------------------------------------------------------
|
||||
SAM repliable datagrams : forwarding datagrams
|
||||
----------------------------------------------------------------------
|
||||
<h3>SAM repliable datagrams : forwarding datagrams</h3>
|
||||
<p>
|
||||
When creating a datagram session, the client can ask SAM to forward
|
||||
incoming messages to a specified ip:port. It does so by issuing the
|
||||
CREATE command with PORT and HOST options :
|
||||
|
||||
<pre>
|
||||
-> SESSION CREATE
|
||||
STYLE=DATAGRAM
|
||||
ID={$nickname}
|
||||
DESTINATION={$private_destination_key,TRANSIENT}
|
||||
PORT={$port}
|
||||
[HOST={$host}]
|
||||
ID=$nickname
|
||||
DESTINATION={$privkey,TRANSIENT}
|
||||
PORT=$port
|
||||
[HOST=$host]
|
||||
[option=value]*
|
||||
</pre>
|
||||
|
||||
* {$host} is the hostname or IP address of the datagram server to
|
||||
</p><p>
|
||||
The $privkey is the base 64 of the concatenation of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>
|
||||
followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_PrivateKey">Private Key</a>
|
||||
followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_SigningPrivateKey">Signing Private Key</a>,
|
||||
which is 884 or more base 64 characters (663 or more bytes in binary),
|
||||
depending on signature type.
|
||||
The binary format is specified in <a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/PrivateKeyFile.html">Private Key File</a>.
|
||||
|
||||
</p><p>
|
||||
$host is the hostname or IP address of the datagram server to
|
||||
which SAM will forward datagrams. If not given, SAM takes the
|
||||
IP of the socket that issued the forward command.
|
||||
|
||||
* {$port} is the port number of the datagram server to which SAM
|
||||
</p><p>
|
||||
$port is the port number of the datagram server to which SAM
|
||||
will forward datagrams.
|
||||
|
||||
</p><p>
|
||||
When a datagram arrives, the bridge sends to the specified host:port
|
||||
a message containing the following data :
|
||||
|
||||
${sender_base64_destination_key}\n{$datagram_payload}
|
||||
<pre>
|
||||
$destination\n$datagram_payload
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
</p>
|
||||
|
||||
|
||||
----------------------------------------------------------------------
|
||||
SAM anonymous datagrams
|
||||
----------------------------------------------------------------------
|
||||
<h3>SAM anonymous datagrams</h3>
|
||||
<p>
|
||||
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 32768 bytes.
|
||||
|
||||
</p><p>
|
||||
Minimum size is 1. For best delivery reliability, recommended maximum
|
||||
size is approximately 11 KB.
|
||||
|
||||
</p><p>
|
||||
After establishing a SAM session with STYLE=RAW, the client can
|
||||
send anonymous datagrams through the SAM bridge exactly the same way
|
||||
he sends non anonymous datagrams.
|
||||
|
||||
</p><p>
|
||||
Both ways of receiving datagrams are also available for anonymous
|
||||
datagrams.
|
||||
|
||||
</p><p>
|
||||
When anonymous datagrams are to be written to the socket that created
|
||||
the session,the bridge delivers it to the client via:
|
||||
|
||||
<pre>
|
||||
<- RAW RECEIVED
|
||||
SIZE=$numBytes\n[$numBytes of data]
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
When anonymous datagrams are to be forwarded to some host:port,
|
||||
the bridge sends to the specified host:port a message containing
|
||||
the following data :
|
||||
|
||||
{$datagram_payload}
|
||||
<pre>
|
||||
$datagram_payload
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
For an alternate method of sending anonymous datagrams, see <a href="#dgsend">RAW SEND</a>.
|
||||
</p>
|
||||
|
||||
----------------------------------------------------------------------
|
||||
V1/V2 Compatible Datagram Handling
|
||||
----------------------------------------------------------------------
|
||||
|
||||
<h3 id="dgsend">DATAGRAM SEND, RAW SEND (V1/V2 Compatible Datagram Handling)</h3>
|
||||
<p>
|
||||
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 <a href="sam">SAM V1</a> and <a href="samv2">SAM V2</a>.
|
||||
|
||||
</p><p>
|
||||
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 <a href="sam">SAM V1</a> and <a href="samv2">SAM V2</a>.
|
||||
|
||||
</p><p>
|
||||
These commands do <i>not</i> 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
|
||||
----------------------------------------------------------------------
|
||||
<h3>SAM utility functionality</h3>
|
||||
<p>
|
||||
The following message can be used by the client to query the SAM
|
||||
bridge for name resolution:
|
||||
|
||||
<pre>
|
||||
NAMING LOOKUP
|
||||
NAME=$name
|
||||
</pre>
|
||||
|
||||
which is answered by
|
||||
|
||||
<pre>
|
||||
NAMING REPLY
|
||||
RESULT=$result
|
||||
NAME=$name
|
||||
[VALUE=$base64key]
|
||||
[VALUE=$destination]
|
||||
[MESSAGE=$message]
|
||||
</pre>
|
||||
|
||||
|
||||
</p><p>
|
||||
The RESULT value may be one of:
|
||||
|
||||
<pre>
|
||||
OK
|
||||
INVALID_KEY
|
||||
KEY_NOT_FOUND
|
||||
</pre>
|
||||
|
||||
If NAME=ME, then the reply will contain the base64key used by the
|
||||
</p><p>
|
||||
If NAME=ME, then the reply will contain the destination used by the
|
||||
current session (useful if you're using a TRANSIENT one). If $result
|
||||
is not OK, MESSAGE may convey a descriptive message, such as "bad
|
||||
format", etc.
|
||||
|
||||
</p><p>
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
|
||||
</p><p>
|
||||
Public and private base64 keys can be generated using the following
|
||||
message:
|
||||
|
||||
<pre>
|
||||
DEST GENERATE
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
which is answered by
|
||||
|
||||
<pre>
|
||||
DEST REPLY
|
||||
PUB=$pubkey
|
||||
PUB=$destination
|
||||
PRIV=$privkey
|
||||
</pre>
|
||||
|
||||
</p><p>
|
||||
As of I2P 0.9.14, an optional parameter SIGNATURE_TYPE is supported.
|
||||
The SIGNATURE_TYPE value may be any name (e.g. ECDSA_SHA256_P256, case insensitive) or number (e.g. 1)
|
||||
that is supported by <a href="{{ site_url('docs/spec/common-structures') }}#type_Certificate">Key Certificates</a>.
|
||||
The default is DSA_SHA1.
|
||||
|
||||
----------------------------------------------------------------------
|
||||
RESULT values
|
||||
----------------------------------------------------------------------
|
||||
</p><p>
|
||||
The $destination is the base 64 of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>,
|
||||
which is 516 or more base 64 characters (387 or more bytes in binary),
|
||||
depending on signature type.
|
||||
|
||||
</p><p>
|
||||
The $privkey is the base 64 of the concatenation of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>
|
||||
followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_PrivateKey">Private Key</a>
|
||||
followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_SigningPrivateKey">Signing Private Key</a>,
|
||||
which is 884 or more base 64 characters (663 or more bytes in binary),
|
||||
depending on signature type.
|
||||
The binary format is specified in <a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/PrivateKeyFile.html">Private Key File</a>.
|
||||
|
||||
<h3>RESULT values</h3>
|
||||
<p>
|
||||
These are the values that can be carried by the RESULT field, with
|
||||
their meaning:
|
||||
|
||||
<pre>
|
||||
OK Operation completed successfully
|
||||
CANT_REACH_PEER The peer exists, but cannot be reached
|
||||
DUPLICATED_DEST The specified Destination is already in use
|
||||
@ -535,39 +733,35 @@ their meaning:
|
||||
KEY_NOT_FOUND The naming system can't resolve the given name
|
||||
PEER_NOT_FOUND The peer cannot be found on the network
|
||||
TIMEOUT Timeout while waiting for an event (e.g. peer answer)
|
||||
</pre>
|
||||
|
||||
|
||||
----------------------------------------------------------------------
|
||||
Tunnel, I2CP, and Streaming Options
|
||||
----------------------------------------------------------------------
|
||||
|
||||
<h3 id="options">Tunnel, I2CP, and Streaming Options</h3>
|
||||
<p>
|
||||
These options may be passed in as name=value pairs at the end of a
|
||||
SAM SESSION CREATE line.
|
||||
|
||||
</p><p>
|
||||
All sessions may include <a href="{{ site_url('docs/protocol/i2cp') }}#options">I2CP options such as tunnel lengths</a>.
|
||||
STREAM sessions may include <a href="{{ site_url('docs/api/streaming') }}#options">Streaming lib options</a>.
|
||||
See those references for option names and defaults.
|
||||
|
||||
|
||||
----------------------------------------------------------------------
|
||||
BASE 64 Notes
|
||||
----------------------------------------------------------------------
|
||||
<h3>BASE 64 Notes</h3>
|
||||
|
||||
<p>
|
||||
Base 64 encoding must use the I2P standard Base 64 alphabet "A-Z, a-z, 0-9, -, ~".
|
||||
</p>
|
||||
|
||||
|
||||
----------------------------------------------------------------------
|
||||
Client library implementations:
|
||||
----------------------------------------------------------------------
|
||||
<h3>Client library implementations</h3>
|
||||
<p>
|
||||
Client libraries are available for C, C++, C#, Perl, and Python.
|
||||
These are in the apps/sam/ directory in the <a href="{{ get_url('downloads_list') }}">I2P Source Package</a>.
|
||||
Some may be older and have not been updated for SAMv3 support.
|
||||
</p>
|
||||
|
||||
|
||||
----------------------------------------------------------------------
|
||||
Default SAM Setup
|
||||
----------------------------------------------------------------------
|
||||
|
||||
<h3>Default SAM Setup</h3>
|
||||
<p>
|
||||
The default SAM port is 7656. SAM is not enabled by default in the I2P Router;
|
||||
it must be started manually, or configured to start automatically,
|
||||
on the configure clients page in the router console, or in the clients.config file.
|
||||
@ -575,5 +769,5 @@ The default SAM UDP port is 7655, listening on 0.0.0.0.
|
||||
These may be changed by adding the arguments sam.udp.port=nnnnn and/or
|
||||
sam.udp.host=w.x.y.z to the invocation.
|
||||
|
||||
</pre>
|
||||
</p>
|
||||
{% endblock %}
|
||||
|
||||
Reference in New Issue
Block a user