kytv/I2P_Website
1
0
Fork 0
forked from I2P_Developers/i2p.www
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

SAM:

Browse Source 
- 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:
zzz
2015-05-12 14:24:36 +00:00
parent d521011cbf
commit aa3a27f1d1
3 changed files with 415 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,7 +1,7 @@
{% extends "global/layout.html" %} {% extends "global/layout.html" %}
{% block title %}SAM V1 Specification{% endblock %} {% block title %}SAM V1 Specification{% endblock %}
{% block lastupdated %}September 2014{% endblock %} {% block lastupdated %}May 2015{% endblock %}
{% block accuratefor %}0.9.15{% endblock %} {% block accuratefor %}0.9.20{% endblock %}
{% block content %} {% block content %}
<p>Specified below is version 1 of a simple client protocol for interacting with <p>Specified below is version 1 of a simple client protocol for interacting with
I2P. 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 "ONE TWO C=D A=B" are both perfectly valid constructions). In
addition, the protocol is case-sensitive. 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: Communication can take three distinct forms:
* <a href="{{ site_url('docs/api/streaming') }}">Virtual streams</a> * <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') }}#repliable">Repliable datagrams</a> (messages with a FROM field)
@@ -164,11 +168,16 @@ forth to manage the streams, as listed below:
STREAM CONNECT STREAM CONNECT
ID=$id ID=$id
DESTINATION=$base64key DESTINATION=$destination
This establishes a new virtual connection from the local destination This establishes a new virtual connection from the local destination
to the specified peer, marking it with the session-scoped unique ID. 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 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: The SAM bridge must reply to this with a stream status message:
STREAM STATUS STREAM STATUS
@@ -193,7 +202,7 @@ On the receiving end, the SAM bridge simply notifies the client as
follows: follows:
STREAM CONNECTED STREAM CONNECTED
DESTINATION=$base64key DESTINATION=$destination
ID=$id ID=$id
This tells the client that the given destination has created a virtual 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 the given unique ID, that is an ASCII base 10 integer from -1 through
-(2^31-1). -(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 When the client wants to send data on the virtual connection, they
do so as follows: do so as follows:
@@ -272,15 +285,19 @@ After establishing a SAM session with STYLE=DATAGRAM, the client can
send the SAM bridge: send the SAM bridge:
DATAGRAM SEND DATAGRAM SEND
DESTINATION=$base64key DESTINATION=$destination
SIZE=$numBytes\n[$numBytes of data] SIZE=$numBytes\n[$numBytes of data]
When a datagram arrives, the bridge delivers it to the client via: When a datagram arrives, the bridge delivers it to the client via:
DATAGRAM RECEIVED DATAGRAM RECEIVED
DESTINATION=$base64key DESTINATION=$destination
SIZE=$numBytes\n[$numBytes of data] 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 The SAM bridge never exposes to the client the authentication headers
or other fields, merely the data that the sender provided. This or other fields, merely the data that the sender provided. This
continues until the session is closed (by the client dropping the 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: send the SAM bridge:
RAW SEND RAW SEND
DESTINATION=$base64key DESTINATION=$destination
SIZE=$numBytes\n[$numBytes of data] 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 When a raw datagram arrives, the bridge delivers it to the client
via: via:
@@ -324,7 +345,7 @@ which is answered by
NAMING REPLY NAMING REPLY
RESULT=$result RESULT=$result
NAME=$name NAME=$name
[VALUE=$base64key] [VALUE=$destination]
[MESSAGE=$message] [MESSAGE=$message]
@@ -334,11 +355,15 @@ The RESULT value may be one of:
INVALID_KEY INVALID_KEY
KEY_NOT_FOUND 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 current session (useful if you're using a TRANSIENT one). If $result
is not OK, MESSAGE may convey a descriptive message, such as "bad is not OK, MESSAGE may convey a descriptive message, such as "bad
format", etc. 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 Public and private base64 keys can be generated using the following
message: message:
@@ -347,7 +372,7 @@ message:
which is answered by which is answered by
DEST REPLY DEST REPLY
PUB=$pubkey PUB=$destination
PRIV=$privkey PRIV=$privkey
As of I2P 0.9.14, an optional parameter SIGNATURE_TYPE is supported. 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>. that is supported by <a href="{{ site_url('docs/spec/common-structures') }}#type_Certificate">Key Certificates</a>.
The default is DSA_SHA1. 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 RESULT values
---------------------------------------------------------------------- ----------------------------------------------------------------------

56
i2p2www/pages/site/docs/api/samv2.html
View File

@@ -1,7 +1,7 @@
{% extends "global/layout.html" %} {% extends "global/layout.html" %}
{% block title %}SAM V2 Specification{% endblock %} {% block title %}SAM V2 Specification{% endblock %}
{% block lastupdated %}September 2014{% endblock %} {% block lastupdated %}May 2015{% endblock %}
{% block accuratefor %}0.9.15{% endblock %} {% block accuratefor %}0.9.20{% endblock %}
{% block content %} {% block content %}
<p>Specified below is a simple client protocol for interacting with I2P. <p>Specified below is a simple client protocol for interacting with I2P.
</p> </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 "ONE TWO C=D A=B" are both perfectly valid constructions). In
addition, the protocol is case-sensitive. 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: Communication can take three distinct forms:
* <a href="{{ site_url('docs/api/streaming') }}">Virtual streams</a> * <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') }}#repliable">Repliable datagrams</a> (messages with a FROM field)
@@ -168,11 +172,15 @@ forth to manage the streams, as listed below:
STREAM CONNECT STREAM CONNECT
ID=$id ID=$id
DESTINATION=$base64key DESTINATION=$destination
This establishes a new virtual connection from the local destination This establishes a new virtual connection from the local destination
to the specified peer, marking it with the session-scoped unique ID. 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 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: The SAM bridge replies to this with a stream status message:
STREAM STATUS STREAM STATUS
@@ -197,7 +205,7 @@ On the receiving end, the SAM bridge simply notifies the client as
follows: follows:
STREAM CONNECTED STREAM CONNECTED
DESTINATION=$base64key DESTINATION=$destination
ID=$id ID=$id
This tells the client that the given destination has created a virtual 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 the given unique ID, that is an ASCII base 10 integer from -1 through
-(2^31-1). -(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 When the client wants to send data on the virtual connection, they
do so as follows: do so as follows:
@@ -329,15 +341,19 @@ After establishing a SAM session with STYLE=DATAGRAM, the client can
send the SAM bridge: send the SAM bridge:
DATAGRAM SEND DATAGRAM SEND
DESTINATION=$base64key DESTINATION=$destination
SIZE=$numBytes\n[$numBytes of data] SIZE=$numBytes\n[$numBytes of data]
When a datagram arrives, the bridge delivers it to the client via: When a datagram arrives, the bridge delivers it to the client via:
DATAGRAM RECEIVED DATAGRAM RECEIVED
DESTINATION=$base64key DESTINATION=$destination
SIZE=$numBytes\n[$numBytes of data] 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 The SAM bridge never exposes to the client the authentication headers
or other fields, merely the data that the sender provided. This or other fields, merely the data that the sender provided. This
continues until the session is closed (by the client dropping the 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: send the SAM bridge:
RAW SEND RAW SEND
DESTINATION=$base64key DESTINATION=$destination
SIZE=$numBytes\n[$numBytes of data] 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 When a raw datagram arrives, the bridge delivers it to the client
via: via:
@@ -381,7 +401,7 @@ which is answered by
NAMING REPLY NAMING REPLY
RESULT=$result RESULT=$result
NAME=$name NAME=$name
[VALUE=$base64key] [VALUE=$destination]
[MESSAGE=$message] [MESSAGE=$message]
@@ -391,11 +411,16 @@ The RESULT value may be one of:
INVALID_KEY INVALID_KEY
KEY_NOT_FOUND 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 current session (useful if you're using a TRANSIENT one). If $result
is not OK, MESSAGE may convey a descriptive message, such as "bad is not OK, MESSAGE may convey a descriptive message, such as "bad
format", etc. 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 Public and private base64 keys can be generated using the following
message: message:
@@ -404,7 +429,7 @@ message:
which is answered by which is answered by
DEST REPLY DEST REPLY
PUB=$pubkey PUB=$destination
PRIV=$privkey PRIV=$privkey
As of I2P 0.9.14, an optional parameter SIGNATURE_TYPE is supported. 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>. that is supported by <a href="{{ site_url('docs/spec/common-structures') }}#type_Certificate">Key Certificates</a>.
The default is DSA_SHA1. 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 RESULT values
---------------------------------------------------------------------- ----------------------------------------------------------------------

452
i2p2www/pages/site/docs/api/samv3.html
View File

@@ -1,7 +1,7 @@
{% extends "global/layout.html" %} {% extends "global/layout.html" %}
{% block title %}SAM V3{% endblock %} {% block title %}SAM V3{% endblock %}
{% block lastupdated %}July 2014{% endblock %} {% block lastupdated %}May 2015{% endblock %}
{% block accuratefor %}0.9.14{% endblock %} {% block accuratefor %}0.9.20{% endblock %}
{% block content %} {% block content %}
<p>Specified below is a simple client protocol for interacting with I2P. <p>Specified below is a simple client protocol for interacting with I2P.
</p> </p>
@@ -52,20 +52,20 @@ Version 3.1 was introduced in I2P release 0.9.14.
</p> </p>
<h2>Version 3 Protocol</h2> <h2>Version 3 Protocol</h2>
<pre> <h3>Simple Anonymous Messaging (SAM version 3.0) Specification Overview</h3>
---------------------------------------------------------------------- <p>
Simple Anonymous Messaging (SAM version 3.0) Specification
----------------------------------------------------------------------
Client application talks to SAM bridge, which deals with Client application talks to SAM bridge, which deals with
all of the I2P functionality (using the streaming all of the I2P functionality (using the streaming
lib for virtual streams, or I2CP directly for async messages). lib for virtual streams, or I2CP directly for async messages).
</p><p>
All client&lt;--&gt;SAM bridge communication is unencrypted and All client&lt;--&gt;SAM bridge communication is unencrypted and
unauthenticated. Access to the SAM unauthenticated. Access to the SAM
bridge should be protected through firewalls or other means bridge should be protected through firewalls or other means
(perhaps the bridge may have ACLs on what IPs it accepts (perhaps the bridge may have ACLs on what IPs it accepts
connections from). connections from).
</p><p>
All of these SAM messages are sent on a single line in plain ASCII, All of these SAM messages are sent on a single line in plain ASCII,
terminated by the newline character (\n). The formatting shown terminated by the newline character (\n). The formatting shown
below is merely for readability, and while the first two words in below is merely for readability, and while the first two words in
@@ -77,70 +77,96 @@ In the following, message examples are preceded by "-&gt; " for
messages sent by the client to the SAM bridge, and by "&lt;- " for messages sent by the client to the SAM bridge, and by "&lt;- " for
messages sent by the SAM bridge to the client. messages sent by the SAM bridge to the client.
I2P communications can take three distinct forms: </p><p>
* <a href="{{ site_url('docs/api/streaming') }}">Virtual streams</a> SAM messages are interpreted in UTF-8. Key=value pairs must be separated by
* <a href="{{ site_url('docs/spec/datagrams') }}#repliable">Repliable datagrams</a> (messages with a FROM field) a single space. Values may be enclosed in double quotes if they contain spaces,
* <a href="{{ site_url('docs/spec/datagrams') }}#raw">Anonymous datagrams</a> (raw anonymous messages) 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 I2P communications are supported by I2P sessions, and each I2P
session is bound to an address (called destination). An I2P session session is bound to an address (called destination). An I2P session
is associated with one of the three types above, and cannot carry is associated with one of the three types above, and cannot carry
communications of another type. communications of another type.
</p>
<h3>SAM connection handshake</h3>
---------------------------------------------------------------------- <p>
SAM connection handshake
----------------------------------------------------------------------
No SAM communication can occur until after the client and bridge have No SAM communication can occur until after the client and bridge have
agreed on a protocol version, which is done by the client sending agreed on a protocol version, which is done by the client sending
a HELLO and the bridge sending a HELLO REPLY: a HELLO and the bridge sending a HELLO REPLY:
<pre>
-&gt; HELLO VERSION MIN=$min MAX=$max -&gt; HELLO VERSION MIN=$min MAX=$max
</pre>
and and
<pre>
&lt;- HELLO REPLY RESULT=OK VERSION=3.1 &lt;- 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. 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 SAM will always return the highest version possible given the
MIN and MAX constraints, or 3.1 if no constraints are given. MIN and MAX constraints, or 3.1 if no constraints are given.
If the SAM bridge cannot find a suitable version, it replies with : If the SAM bridge cannot find a suitable version, it replies with :
<pre>
&lt;- HELLO REPLY RESULT=NOVERSION &lt;- HELLO REPLY RESULT=NOVERSION
</pre>
If some error occurred, such as a bad request format, it replies with : If some error occurred, such as a bad request format, it replies with :
<pre>
&lt;- HELLO REPLY RESULT=I2P_ERROR MESSAGE=$message
</pre>
</p>
&lt;- HELLO REPLY RESULT=I2P_ERROR MESSAGE={$message} <h3>SAM sessions</h3>
<p>
----------------------------------------------------------------------
SAM sessions
----------------------------------------------------------------------
A SAM session is created by a client opening a socket to the SAM A SAM session is created by a client opening a socket to the SAM
bridge, operating a handshake, and sending a SESSION CREATE message, bridge, operating a handshake, and sending a SESSION CREATE message,
and the session terminates when the socket is disconnected. and the session terminates when the socket is disconnected.
</p><p>
Each registered I2P Destination is uniquely associated with a session ID Each registered I2P Destination is uniquely associated with a session ID
(or nickname). (or nickname).
</p><p>
Each session is uniquely associated with : Each session is uniquely associated with :
* the socket from which the client creates the session <ul><li>
* its ID (or nickname) 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 The session creation message can only use one of these forms (messages
received through other forms are answered with an error message) : received through other forms are answered with an error message) :
<pre>
-&gt; SESSION CREATE -&gt; SESSION CREATE
STYLE={STREAM,DATAGRAM,RAW} STYLE={STREAM,DATAGRAM,RAW}
ID={$nickname} ID=$nickname
DESTINATION={$private_destination_key,TRANSIENT} DESTINATION={$privkey,TRANSIENT}
[option=value]* [option=value]*
</pre>
</p><p>
DESTINATION specifies what destination should be used for DESTINATION specifies what destination should be used for
sending and receiving messages/streams. It is the base 64 encoding of sending and receiving messages/streams.
the concatenation of the destination, private key, and signing private key. 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. 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 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 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>. supported by <a href="{{ site_url('docs/spec/common-structures') }}#type_Certificate">Key Certificates</a>.
The default is DSA_SHA1. 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 Additional options given are passed to the I2P session
configuration if not interpreted by the SAM bridge (e.g. 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 The SAM bridge itself should already be configured with what router
it should communicate over I2P through (though if need be there may 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 be a way to provide an override, e.g. i2cp.tcp.host=localhost and
i2cp.tcp.port=7654). i2cp.tcp.port=7654).
</p><p>
After receiving the session create message, the SAM bridge will reply After receiving the session create message, the SAM bridge will reply
with a session status message, as follows: with a session status message, as follows:
</p><p>
If the creation was successful : If the creation was successful :
&lt;- SESSION STATUS RESULT=OK DESTINATION={$private_destination_key} <pre>
&lt;- 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 : If the nickname is already associated with a session :
<pre>
&lt;- SESSION STATUS RESULT=DUPLICATED_ID &lt;- SESSION STATUS RESULT=DUPLICATED_ID
</pre>
</p><p>
If the destination is already in use : If the destination is already in use :
<pre>
&lt;- SESSION STATUS RESULT=DUPLICATED_DEST &lt;- SESSION STATUS RESULT=DUPLICATED_DEST
</pre>
</p><p>
If the destination is not a valid private destination key : If the destination is not a valid private destination key :
<pre>
&lt;- SESSION STATUS RESULT=INVALID_KEY &lt;- SESSION STATUS RESULT=INVALID_KEY
</pre>
</p><p>
If some other error has occurred : If some other error has occurred :
&lt;- SESSION STATUS RESULT=I2P_ERROR MESSAGE={$message} <pre>
&lt;- SESSION STATUS RESULT=I2P_ERROR MESSAGE=$message
</pre>
</p><p>
If it's not OK, the MESSAGE should contain human-readable information If it's not OK, the MESSAGE should contain human-readable information
as to why the session could not be created. as to why the session could not be created.
</p><p>
SAM sessions live and die with the socket they are associated with. SAM sessions live and die with the socket they are associated with.
When the socket is closed, the session dies, and all communications 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 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. the session dies for any reason, the SAM bridge closes the socket.
</p>
---------------------------------------------------------------------- <h3>SAM virtual streams</h3>
SAM virtual streams <p>
----------------------------------------------------------------------
Virtual streams are guaranteed to be sent reliably and in order, with Virtual streams are guaranteed to be sent reliably and in order, with
failure and success notification as soon as it is available. failure and success notification as soon as it is available.
</p><p>
Streams are bidirectional communication sockets between two I2P Streams are bidirectional communication sockets between two I2P
destinations, but their opening has to be requested by one of them. destinations, but their opening has to be requested by one of them.
Hereafter, CONNECT commands are used by the SAM client for such a Hereafter, CONNECT commands are used by the SAM client for such a
request. FORWARD / ACCEPT commands are used by the SAM client when request. FORWARD / ACCEPT commands are used by the SAM client when
he wants to listen to requests coming from other I2P destinations. he wants to listen to requests coming from other I2P destinations.
</p>
----------------------------- <h3>SAM virtual streams : CONNECT</h3>
SAM virtual streams : CONNECT <p>
-----------------------------
A client asks for a connection by : A client asks for a connection by :
* opening a new socket with the SAM bridge <ul><li>
* passing the same HELLO handshake as above opening a new socket with the SAM bridge
* sending the connection command : </li><li>
passing the same HELLO handshake as above
</li><li>
sending the connection command :
</li></ul>
<pre>
-&gt; STREAM CONNECT -&gt; STREAM CONNECT
ID={$nickname} ID=$nickname
DESTINATION=$peer_public_base64_key DESTINATION=$destination
[SILENT={true,false}] [SILENT={true,false}]
</pre>
</p><p>
This establishes a new virtual connection from the local session 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 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. on the socket : if the connection fails, the socket will be closed.
If the connection succeeds, all remaining data passing through the If the connection succeeds, all remaining data passing through the
current socket is forwarded from and to the connected I2P destination current socket is forwarded from and to the connected I2P destination
peer. peer.
</p><p>
If SILENT=false, which is the default value, the SAM bridge sends a If SILENT=false, which is the default value, the SAM bridge sends a
last message to its client before forwarding or shutting down the last message to its client before forwarding or shutting down the
socket : socket :
<pre>
&lt;- STREAM STATUS &lt;- STREAM STATUS
RESULT=$result RESULT=$result
[MESSAGE=...] [MESSAGE=...]
</pre>
</p><p>
The RESULT value may be one of: The RESULT value may be one of:
<pre>
OK OK
CANT_REACH_PEER CANT_REACH_PEER
I2P_ERROR I2P_ERROR
INVALID_KEY INVALID_KEY
INVALID_ID INVALID_ID
TIMEOUT TIMEOUT
</pre>
</p><p>
If the RESULT is OK, all remaining data passing through the If the RESULT is OK, all remaining data passing through the
current socket is forwarded from and to the connected I2P destination current socket is forwarded from and to the connected I2P destination
peer. If the connection was not possible (timeout, etc), peer. If the connection was not possible (timeout, etc),
RESULT will contain the appropriate error value (accompanied by an RESULT will contain the appropriate error value (accompanied by an
optional human-readable MESSAGE), and the SAM bridge closes the optional human-readable MESSAGE), and the SAM bridge closes the
socket. socket.
</p>
---------------------------- <h3>SAM virtual streams : ACCEPT</h3>
SAM virtual streams : ACCEPT <p>
----------------------------
A client waits for an incoming connection request by : A client waits for an incoming connection request by :
* opening a new socket with the SAM bridge <ul><li>
* passing the same HELLO handshake as above opening a new socket with the SAM bridge
* sending the accept command : </li><li>
passing the same HELLO handshake as above
</li><li>
sending the accept command :
</li></ul>
<pre>
-&gt; STREAM ACCEPT -&gt; STREAM ACCEPT
ID={$nickname} ID=$nickname
[SILENT={true,false}] [SILENT={true,false}]
</pre>
</p><p>
This makes the session ${nickname} listen for one incoming This makes the session ${nickname} listen for one incoming
connection request from the I2P network. connection request from the I2P network.
</p><p>
The SAM bridge answers with : The SAM bridge answers with :
<pre>
&lt;- STREAM STATUS &lt;- STREAM STATUS
RESULT=$result RESULT=$result
[MESSAGE=...] [MESSAGE=...]
</pre>
</p><p>
The RESULT value may be one of: The RESULT value may be one of:
<pre>
OK OK
I2P_ERROR I2P_ERROR
INVALID_ID INVALID_ID
</pre>
</p><p>
If the result is not OK, the socket is closed immediately by the SAM 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 bridge. If the result is OK, the SAM bridge starts waiting for an
incoming connection request from another I2P peer. When a request incoming connection request from another I2P peer. When a request
arrives, the SAM bridge accepts it and : 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 on the client socket : all remaining data passing through the
current socket is forwarded from and to the connected I2P destination current socket is forwarded from and to the connected I2P destination
peer. 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 sends the client a ASCII line containing the base64 public destination key
of the requesting peer. After this '\n' terminated line, all remaining data of the requesting peer. After this '\n' terminated line, all remaining data
passing through the current socket is forwarded from and to the connected passing through the current socket is forwarded from and to the connected
I2P destination peer, until one of the peer closes the socket. I2P destination peer, until one of the peer closes the socket.
</p>
----------------------------- <h3>SAM virtual streams : FORWARD</h3>
SAM virtual streams : FORWARD <p>
-----------------------------
A client can use a regular socket server and wait for connection requests A client can use a regular socket server and wait for connection requests
coming from I2P. For that, the client has to : coming from I2P. For that, the client has to :
* open a new socket with the SAM bridge <ul><li>
* pass the same HELLO handshake as above open a new socket with the SAM bridge
* send the forward command : </li><li>
pass the same HELLO handshake as above
</li><li>
send the forward command :
</ul><li>
<pre>
-&gt; STREAM FORWARD -&gt; STREAM FORWARD
ID={$nickname} ID=$nickname
PORT={$port} PORT=$port
[HOST={$host}] [HOST=$host]
[SILENT={true,false}] [SILENT={true,false}]
</pre>
</p><p>
This makes the session ${nickname} listen for incoming This makes the session ${nickname} listen for incoming
connection requests from the I2P network. connection requests from the I2P network.
</p><p>
The SAM bridge answers with : The SAM bridge answers with :
<pre>
&lt;- STREAM STATUS &lt;- STREAM STATUS
RESULT=$result RESULT=$result
[MESSAGE=...] [MESSAGE=...]
</pre>
</p><p>
The RESULT value may be one of: The RESULT value may be one of:
<pre>
OK OK
I2P_ERROR I2P_ERROR
INVALID_ID 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 SAM will forward connection requests. If not given, SAM takes the IP
of the socket that issued the forward command. 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. forward connection requests. It is mandatory.
</p><p>
When a connection request arrives from I2P, the SAM bridge requests a 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 : 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 current socket is forwarded from and to the connected I2P destination
peer. 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 sends on the obtained socket an ASCII line containing the base64 public
destination key of the requesting peer. After this '\n' terminated line, destination key of the requesting peer. After this '\n' terminated line,
all remaining data passing through the socket is forwarded from and to 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 The I2P router will stop listening to incoming connection requests as
soon as the "forwarding" socket is closed. soon as the "forwarding" socket is closed.
---------------------------------------------------------------------- <h3>SAM repliable datagrams : sending a datagram</h3>
SAM repliable datagrams : sending a datagram <p>
----------------------------------------------------------------------
While I2P doesn't inherently contain a FROM address, for ease of use While I2P doesn't inherently contain a FROM address, for ease of use
an additional layer is provided as repliable datagrams - unordered an additional layer is provided as repliable datagrams - unordered
and unreliable messages of up to 31744 bytes that include a FROM 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 is authenticated internally by SAM (making use of the destination's
signing key to verify the source) and includes replay prevention. signing key to verify the source) and includes replay prevention.
</p><p>
Minimum size is 1. For best delivery reliability, recommended maximum Minimum size is 1. For best delivery reliability, recommended maximum
size is approximately 11 KB. size is approximately 11 KB.
</p><p>
After establishing a SAM session with STYLE=DATAGRAM, the client can After establishing a SAM session with STYLE=DATAGRAM, the client can
send datagrams through SAM's UDP port (7655). 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 The first line of a datagram sent through this port has to be in the
following format : following format :
3.0 {$nickname} {$base64_public_destination_key} <p>
3.0 $nickname $destination
</p>
* 3.0 is the version of SAM <ul><li>
* {$nickname} is the id of the DGRAM session that will be used 3.0 is the version of SAM
* {$base64_public_destination_key} is the destination of the </li><li>
datagram $nickname is the id of the DGRAM session that will be used
* this line is '\n' terminated. </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 The first line will be discarded by SAM before sending the remaining
of the message to the specified destination. of the message to the specified destination.
---------------------------------------------------------------------- </p><p>
SAM repliable datagrams : receiving a datagram 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 Received datagrams are written by SAM on the socket from which the
datagram session was opened, unless specified otherwise by the CREATE datagram session was opened, unless specified otherwise by the CREATE
command. command.
</p><p>
When a datagram arrives, the bridge delivers it to the client via the When a datagram arrives, the bridge delivers it to the client via the
message : message :
<pre>
&lt;- DATAGRAM RECEIVED &lt;- DATAGRAM RECEIVED
DESTINATION=$base64key DESTINATION=$destination
SIZE=$numBytes\n[$numBytes of data] 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 The SAM bridge never exposes to the client the authentication headers
or other fields, merely the data that the sender provided. This or other fields, merely the data that the sender provided. This
continues until the session is closed (by the client dropping the continues until the session is closed (by the client dropping the
connection). connection).
---------------------------------------------------------------------- <h3>SAM repliable datagrams : forwarding datagrams</h3>
SAM repliable datagrams : forwarding datagrams <p>
----------------------------------------------------------------------
When creating a datagram session, the client can ask SAM to forward 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 incoming messages to a specified ip:port. It does so by issuing the
CREATE command with PORT and HOST options : CREATE command with PORT and HOST options :
<pre>
-&gt; SESSION CREATE -&gt; SESSION CREATE
STYLE=DATAGRAM STYLE=DATAGRAM
ID={$nickname} ID=$nickname
DESTINATION={$private_destination_key,TRANSIENT} DESTINATION={$privkey,TRANSIENT}
PORT={$port} PORT=$port
[HOST={$host}] [HOST=$host]
[option=value]* [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 which SAM will forward datagrams. If not given, SAM takes the
IP of the socket that issued the forward command. 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. will forward datagrams.
</p><p>
When a datagram arrives, the bridge sends to the specified host:port When a datagram arrives, the bridge sends to the specified host:port
a message containing the following data : 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>
---------------------------------------------------------------------- <h3>SAM anonymous datagrams</h3>
SAM anonymous datagrams <p>
----------------------------------------------------------------------
Squeezing the most out of I2P's bandwidth, SAM allows clients to send Squeezing the most out of I2P's bandwidth, SAM allows clients to send
and receive anonymous datagrams, leaving authentication and reply and receive anonymous datagrams, leaving authentication and reply
information up to the client themselves. These datagrams are information up to the client themselves. These datagrams are
unreliable and unordered, and may be up to 32768 bytes. unreliable and unordered, and may be up to 32768 bytes.
</p><p>
Minimum size is 1. For best delivery reliability, recommended maximum Minimum size is 1. For best delivery reliability, recommended maximum
size is approximately 11 KB. size is approximately 11 KB.
</p><p>
After establishing a SAM session with STYLE=RAW, the client can After establishing a SAM session with STYLE=RAW, the client can
send anonymous datagrams through the SAM bridge exactly the same way send anonymous datagrams through the SAM bridge exactly the same way
he sends non anonymous datagrams. he sends non anonymous datagrams.
</p><p>
Both ways of receiving datagrams are also available for anonymous Both ways of receiving datagrams are also available for anonymous
datagrams. datagrams.
</p><p>
When anonymous datagrams are to be written to the socket that created When anonymous datagrams are to be written to the socket that created
the session,the bridge delivers it to the client via: the session,the bridge delivers it to the client via:
<pre>
&lt;- RAW RECEIVED &lt;- RAW RECEIVED
SIZE=$numBytes\n[$numBytes of data] SIZE=$numBytes\n[$numBytes of data]
</pre>
</p><p>
When anonymous datagrams are to be forwarded to some host:port, When anonymous datagrams are to be forwarded to some host:port,
the bridge sends to the specified host:port a message containing the bridge sends to the specified host:port a message containing
the following data : 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>
---------------------------------------------------------------------- <h3 id="dgsend">DATAGRAM SEND, RAW SEND (V1/V2 Compatible Datagram Handling)</h3>
V1/V2 Compatible Datagram Handling <p>
----------------------------------------------------------------------
In SAM V3, the preferred way to send datagrams is via the datagram socket 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 at port 7655 as documented above. However, repliable datagrams may be sent
directly via the SAM bridge socket using the DATAGRAM SEND command, 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>. 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 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, 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>. 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 These commands do <i>not</i> support the ID parameter. The datagrams are
sent to the most recently created DATAGRAM- or RAW-style session, 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. as appropriate. Support for the ID parameter may be added in a future release.
---------------------------------------------------------------------- <h3>SAM utility functionality</h3>
SAM utility functionality <p>
----------------------------------------------------------------------
The following message can be used by the client to query the SAM The following message can be used by the client to query the SAM
bridge for name resolution: bridge for name resolution:
<pre>
NAMING LOOKUP NAMING LOOKUP
NAME=$name NAME=$name
</pre>
which is answered by which is answered by
<pre>
NAMING REPLY NAMING REPLY
RESULT=$result RESULT=$result
NAME=$name NAME=$name
[VALUE=$base64key] [VALUE=$destination]
[MESSAGE=$message] [MESSAGE=$message]
</pre>
</p><p>
The RESULT value may be one of: The RESULT value may be one of:
<pre>
OK OK
INVALID_KEY INVALID_KEY
KEY_NOT_FOUND 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 current session (useful if you're using a TRANSIENT one). If $result
is not OK, MESSAGE may convey a descriptive message, such as "bad is not OK, MESSAGE may convey a descriptive message, such as "bad
format", etc. 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 Public and private base64 keys can be generated using the following
message: message:
<pre>
DEST GENERATE DEST GENERATE
</pre>
</p><p>
which is answered by which is answered by
<pre>
DEST REPLY DEST REPLY
PUB=$pubkey PUB=$destination
PRIV=$privkey PRIV=$privkey
</pre>
</p><p>
As of I2P 0.9.14, an optional parameter SIGNATURE_TYPE is supported. 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) 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>. that is supported by <a href="{{ site_url('docs/spec/common-structures') }}#type_Certificate">Key Certificates</a>.
The default is DSA_SHA1. The default is DSA_SHA1.
---------------------------------------------------------------------- </p><p>
RESULT values 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 These are the values that can be carried by the RESULT field, with
their meaning: their meaning:
<pre>
OK Operation completed successfully OK Operation completed successfully
CANT_REACH_PEER The peer exists, but cannot be reached CANT_REACH_PEER The peer exists, but cannot be reached
DUPLICATED_DEST The specified Destination is already in use 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 KEY_NOT_FOUND The naming system can't resolve the given name
PEER_NOT_FOUND The peer cannot be found on the network PEER_NOT_FOUND The peer cannot be found on the network
TIMEOUT Timeout while waiting for an event (e.g. peer answer) TIMEOUT Timeout while waiting for an event (e.g. peer answer)
</pre>
---------------------------------------------------------------------- <h3 id="options">Tunnel, I2CP, and Streaming Options</h3>
Tunnel, I2CP, and Streaming Options <p>
----------------------------------------------------------------------
These options may be passed in as name=value pairs at the end of a These options may be passed in as name=value pairs at the end of a
SAM SESSION CREATE line. 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>. 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>. STREAM sessions may include <a href="{{ site_url('docs/api/streaming') }}#options">Streaming lib options</a>.
See those references for option names and defaults. See those references for option names and defaults.
---------------------------------------------------------------------- <h3>BASE 64 Notes</h3>
BASE 64 Notes
----------------------------------------------------------------------
<p>
Base 64 encoding must use the I2P standard Base 64 alphabet "A-Z, a-z, 0-9, -, ~". Base 64 encoding must use the I2P standard Base 64 alphabet "A-Z, a-z, 0-9, -, ~".
</p>
<h3>Client library implementations</h3>
---------------------------------------------------------------------- <p>
Client library implementations:
----------------------------------------------------------------------
Client libraries are available for C, C++, C#, Perl, and Python. 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>. 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. Some may be older and have not been updated for SAMv3 support.
</p>
<h3>Default SAM Setup</h3>
---------------------------------------------------------------------- <p>
Default SAM Setup
----------------------------------------------------------------------
The default SAM port is 7656. SAM is not enabled by default in the I2P Router; 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, 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. 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 These may be changed by adding the arguments sam.udp.port=nnnnn and/or
sam.udp.host=w.x.y.z to the invocation. sam.udp.host=w.x.y.z to the invocation.
</pre> </p>
{% endblock %} {% endblock %}