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

Close approved proposal 167 and copy to specs

Browse Source
This commit is contained in:
zzz
2025-04-03 11:18:48 -04:00
parent bdbbe936ea
commit 8c7df88a18
6 changed files with 186 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,7 +1,7 @@
{% extends "global/layout.html" %}
{% block title %}SAM V3{% endblock %}
{% block lastupdated %}2024-09{% endblock %}
{% block accuratefor %}API 0.9.63{% endblock %}
{% block lastupdated %}2025-04{% endblock %}
{% block accuratefor %}API 0.9.66{% endblock %}
{% block content %}
<p>SAM is a simple client protocol for interacting with I2P.
SAM is the recommended protocol for non-Java applications to connect to the I2P network,
@ -1631,6 +1631,7 @@ bridge for name resolution:
<pre>
NAMING LOOKUP
NAME=$name
[OPTIONS=true] # Default false, as of router API 0.9.66
</pre>
</p><p>
@ -1642,6 +1643,7 @@ which is answered by
NAME=$name
[VALUE=$destination]
[MESSAGE="$message"]
[OPTION:optionkey="$optionvalue"] # As of router API 0.9.66
</pre>
@ -1673,6 +1675,35 @@ However, in some implementations, a .b32.i2p lookup which is uncached and requir
a network query may fail, as no client tunnels are available for the lookup.
</p>
<h4>Name Lookup Options</h4>
<p>
NAMING LOOKUP is extended as of router API 0.9.66 to support service lookups.
Support may vary by implementation.
See proposal 167 for additional information.
</p><p>
NAMING LOOKUP NAME=example.i2p OPTIONS=true requests the options mapping in the reply.
NAME may be a full base64 destination when OPTIONS=true.
</p><p>
If the destination lookup was successful and options were present in the leaseset,
then in the reply, following the destination,
will be one or more options in the form of OPTION:key=value.
Each option will have a separate OPTION: prefix.
All options from the leaseset will be included, not just service record options.
For example, options for parameters defined in the future may be present.
Example:
</p><p>
NAMING REPLY RESULT=OK NAME=example.i2p VALUE=base64dest OPTION:_smtp._tcp="1 86400 0 0 25 bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.b32.i2p"
</p><p>
Keys containing '=', and keys or values containing a newline,
are considered invalid and the key/value pair will be removed from the reply.
If there are no options found in the leaseset, or if the leaseset was version 1,
then the response will not include any options.
If OPTIONS=true was in the lookup, and the leaseset is not found, a new result value LEASESET_NOT_FOUND will be returned.
</p>
<h4>Destination Key Generation</h4>
</p><p>
@ -1830,6 +1861,7 @@ 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)
LEASESET_NOT_FOUND See Name Lookup Options above. As of router API 0.9.66.
</pre>
<p>

21
i2p2www/pages/site/docs/protocol/i2cp.html
View File

@ -1,7 +1,7 @@
{% extends "global/layout.html" %}
{% block title %}I2CP{% endblock %}
{% block lastupdated %}2025-01{% endblock %}
{% block accuratefor %}0.9.64{% endblock %}
{% block lastupdated %}2025-04{% endblock %}
{% block accuratefor %}0.9.66{% endblock %}
{% block content %}
<p>{% trans -%}
The I2P Client Protocol (I2CP) exposes a strong separation of concerns between
@ -729,7 +729,7 @@ See proposal 123.
<td>
The base 64 of the client name (ignored, UI use only),
followed by a ':', followed by the base 64 of the private
key to use for PSK per-client auth. nnn starts with 0
key to use for PSK per-client auth. nnn starts with 0.
See proposal 123.
</td>
</tr>
@ -760,6 +760,21 @@ See proposals 123, 144, and 145.
<td>{% trans %}For encrypted leasesets. Base 64 SessionKey (44 characters){% endtrans %}</td>
</tr>
<tr>
<td>i2cp.leaseSetOption.nnn
<td>0.9.66</td>
<td>srvKey=srvValue
<td>&nbsp;
<td>&nbsp;
<td>
A service record to be placed in the LeaseSet2 options.
Example:
"_smtp._tcp=1 86400 0 0 25 ...b32.i2p"
nnn starts with 0.
See proposal 167.
</td>
</tr>
<tr>
<td>i2cp.leaseSetPrivateKey
<td>0.9.18</td>

55
i2p2www/spec/common-structures.rst
View File

@ -3,8 +3,8 @@ Common structures Specification
===============================
.. meta::
:category: Design
:lastupdated: 2025-02
:accuratefor: 0.9.65
:lastupdated: 2025-04
:accuratefor: 0.9.66
.. contents::
@ -1264,6 +1264,57 @@ by the Destination_'s SigningPrivateKey_ or the transient key.
{% endhighlight %}
Options
```````
As of API 0.9.66, a standard format for service record options
is defined. See proposal 167 for details.
Options other than service records, using a different format,
may be defined in the future.
LS2 options MUST be sorted by key, so the signature is invariant.
Service record options are defined as follows:
- serviceoption := optionkey optionvalue
- optionkey := _service._proto
- service := The symbolic name of the desired service. Must be lower case. Example: "smtp".
Allowed chars are [a-z0-9-] and must not start or end with a '-'.
Standard identifiers from [REGISTRY]_ or Linux /etc/services must be used if defined there.
- proto := The transport protocol of the desired service. Must be lower case, either "tcp" or "udp".
"tcp" means streaming and "udp" means repliable datagrams.
Protocol indicators for raw datagrams and datagram2 may be defined later.
Allowed chars are [a-z0-9-] and must not start or end with a '-'.
- optionvalue := self | srvrecord[,srvrecord]*
- self := "0" ttl port [appoptions]
- srvrecord := "1" ttl priority weight port target [appoptions]
- ttl := time to live, integer seconds. Positive integer. Example: "86400".
A minimum of 86400 (one day) is recommended, see Recommendations section below for details.
- priority := The priority of the target host, lower value means more preferred. Non-negative integer. Example: "0"
Only useful if more than one record, but required even if just one record.
- weight := A relative weight for records with the same priority. Higher value means more chance of getting picked. Non-negative integer. Example: "0"
Only useful if more than one record, but required even if just one record.
- port := The I2CP port on which the service is to be found. Non-negative integer. Example: "25"
Port 0 is supported but not recommended.
- target := The hostname or b32 of the destination providing the service. A valid hostname as in [NAMING]_. Must be lower case.
Example: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.b32.i2p" or "example.i2p".
b32 is recommended unless the hostname is "well known", i.e. in official or default address books.
- appoptions := arbitrary text specific to the application, must not contain " " or ",". Encoding is UTF-8.
Examples:
In LS2 for aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.b32.i2p, pointing to one SMTP server:
"_smtp._tcp" "1 86400 0 0 25 bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.b32.i2p"
In LS2 for aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.b32.i2p, pointing to two SMTP servers:
"_smtp._tcp" "1 86400 0 0 25 bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.b32.i2p,86400 1 0 25 cccccccccccccccccccccccccccccccccccccccccccc.b32.i2p"
In LS2 for bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.b32.i2p, pointing to itself as a SMTP server:
"_smtp._tcp" "0 999999 25"
Notes
`````
* The public key of the destination was used for the old I2CP-to-I2CP

68
i2p2www/spec/i2cp.rst
View File

@ -3,8 +3,8 @@ I2CP Specification
==================
.. meta::
:category: Protocols
:lastupdated: 2025-02
:accuratefor: 0.9.65
:lastupdated: 2025-04
:accuratefor: 0.9.66
.. contents::
@ -237,6 +237,8 @@ below.
============== ======================
Version Required I2CP Features
============== ======================
0.9.66 Host lookup/reply extensions (see proposal 167)
0.9.62 MessageStatus message Loopback error code
0.9.43 BlindingInfo message supported
@ -887,7 +889,24 @@ Contents
2. 4 byte [Integer]_ request ID
3. 4 byte [Integer]_ timeout (ms)
4. 1 byte [Integer]_ request type
5. SHA-256 [Hash]_ or host name [String]_
5. SHA-256 [Hash]_ or host name [String]_ or [Destination]_
Request types:
==== =================== =======
Type Lookup key (item 5) As of
==== =================== =======
0 Hash
1 host name String
2 Hash 0.9.66
3 host name String 0.9.66
4 Destination 0.9.66
==== =================== =======
Types 2-4 request that the options mapping from the LeaseSet
be returned in the HostReply message.
See proposal 167.
Notes
`````
@ -900,8 +919,6 @@ Notes
the future it may also be useful for remote naming service lookups. The value
may be not be honored for local host name lookups, which should be fast.
* The request type is 0 for Hash and 1 for host name.
* Base 32 host name lookup is supported but it is preferred to convert it to a
Hash first.
@ -926,8 +943,44 @@ Contents
- 3: Private key required (as of 0.9.43)
- 4: Lookup password and private key required (as of 0.9.43)
- 5: Leaseset decryption failure (as of 0.9.43)
- 6: Leaseset lookup failure (as of 0.9.66)
- 7: Lookup type unsupported (as of 0.9.66)
4. [Destination]_, only present if result code is zero,
except may also be returned for lookup types 2-4.
See below.
5. [Mapping]_, only present if result code is zero,
only returned for lookup types 2-4.
As of 0.9.66. See below.
Responses for lookup types 2-4
``````````````````````````````
Proposal 167 defines additional lookup types that
return all options from the leaseset, if present.
For lookup types 2-4, the router must fetch the leaseset,
even if the lookup key is in the address book.
If successful, the HostReply will contain the options Mapping
from the leaseset, and includes it as item 5 after the destination.
If there are no options in the Mapping, or the leaseset was version 1,
it will still be included as an empty Mapping (two bytes: 0 0).
All options from the leaseset will be included, not just service record options.
For example, options for parameters defined in the future may be present.
The returned Mapping may or may not be sorted, implementation-dependent.
On leaseset lookup failure, the reply will contain a new error code 6 (Leaseset lookup failure)
and will not include a mapping.
When error code 6 is returned, the Destination field may or may not be present.
It will be present if a hostname lookup in the address book was successful,
or if a previous lookup was successful and the result was cached,
or if the Destination was present in the lookup message (lookup type 4).
If a lookup type is not supported,
the reply will contain a new error code 7 (lookup type unsupported).
4. [Destination]_, only present if result code is zero.
Notes
`````
@ -940,6 +993,9 @@ Notes
As of 0.9.43, the additional failure codes 2-5 were defined
to support extended errors for "b33" lookups.
See proposals 123 and 149 for additional information.
As of 0.9.66, the additional failure codes 6-7 were defined
to support extended errors for type 2-4 lookups.
See proposal 167 for additional information.
.. _msg-MessagePayload:

8
i2p2www/spec/i2np.rst
View File

@ -3,8 +3,8 @@ I2NP Specification
==================
.. meta::
:category: Protocols
:lastupdated: 2025-02
:accuratefor: 0.9.65
:lastupdated: 2025-04
:accuratefor: 0.9.66
.. contents::
@ -45,6 +45,10 @@ below.
============== ================================================================
API Version Required I2NP Features
============== ================================================================
0.9.66 LeaseSet2 service record options (see proposal 167)
0.9.65 Tunnel build bandwidth parameters (see proposal 168)
0.9.59 Minimum peers will build tunnels through, as of 0.9.63
Minimum floodfill peers will send DSM to, as of 0.9.63

19
i2p2www/spec/proposals/167-service-records.rst
View File

@ -5,13 +5,17 @@ Service Records in LS2
:author: zzz, orignal, eyedeekay
:created: 2024-06-22
:thread: http://zzz.i2p/topics/3641
:lastupdated: 2025-03-23
:status: Open
:lastupdated: 2025-04-03
:status: Closed
:target: 0.9.66
.. contents::
Status
======
Approved on 2nd review 2025-04-01; specs are updated; not yet implemented.
Overview
========
@ -108,7 +112,7 @@ Specification
LS2 Option Specification
---------------------------
LS2 options MUST be sorted by key.
LS2 options MUST be sorted by key, so the signature is invariant.
Defined as follows:
@ -242,7 +246,8 @@ For lookup type 4, item 5 is a Destination.
HostReply Message
``````````````````
For lookup types 2-4, the router fetches the leaseset.
For lookup types 2-4, the router must fetch the leaseset,
even if the lookup key is in the address book.
If successful, the HostReply will contain the options Mapping
from the leaseset, and includes it as item 5 after the destination.
@ -274,8 +279,10 @@ NAMING LOOKUP NAME=example.i2p OPTIONS=true requests the options mapping in the
NAME may be a full base64 destination when OPTIONS=true.
If the destination lookup was successful, in the reply, following the destination,
will be options in the form of OPTION:key=value.
If the destination lookup was successful and options were present in the leaseset,
then in the reply, following the destination,
will be one or more options in the form of OPTION:key=value.
Each option will have a separate OPTION: prefix.
All options from the leaseset will be included, not just service record options.
For example, options for parameters defined in the future may be present.
Example: