From b07091556c248d2cb13de3949314f33e2ea37f3f Mon Sep 17 00:00:00 2001
From: zzz <zzz@i2pmail.org>
Date: Sun, 7 Jan 2024 10:32:34 -0500
Subject: [PATCH] add enctype recommendations to SAM and bittorrent docs
---
i2p2www/pages/site/docs/api/samv3.html | 27 ++++++++++++++-----
.../site/docs/applications/bittorrent.html | 17 ++++++++++--
2 files changed, 36 insertions(+), 8 deletions(-)
diff --git a/i2p2www/pages/site/docs/api/samv3.html b/i2p2www/pages/site/docs/api/samv3.html
index d8641cf30..acc559821 100644
--- a/i2p2www/pages/site/docs/api/samv3.html
+++ b/i2p2www/pages/site/docs/api/samv3.html
@@ -1,7 +1,7 @@
{% extends "global/layout.html" %}
{% block title %}SAM V3{% endblock %}
-{% block lastupdated %}2023-11{% endblock %}
-{% block accuratefor %}API 0.9.59{% endblock %}
+{% block lastupdated %}2024-01{% endblock %}
+{% block accuratefor %}API 0.9.61{% 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,
@@ -252,7 +252,7 @@ To implement a basic TCP-only, peer-to-peer application, the client must support
<li> HELLO VERSION MIN=3.1 MAX=3.1 <br> Needed for all of the remaining ones
<li> DEST GENERATE SIGNATURE_TYPE=7 <br> To generate our private key and destination
<li> NAMING LOOKUP NAME=... <br> To convert .i2p addresses to destinations
-<li> SESSION CREATE STYLE=STREAM ID=... DESTINATION=... <br> Needed for STREAM CONNECT and STREAM ACCEPT
+<li> SESSION CREATE STYLE=STREAM ID=... DESTINATION=... i2cp.leaseSetEncType=4,0<br> Needed for STREAM CONNECT and STREAM ACCEPT
<li> STREAM CONNECT ID=... DESTINATION=... <br> To make outgoing connections
<li> STREAM ACCEPT ID=... <br> To accept incoming connections
</ul>
@@ -260,6 +260,7 @@ To implement a basic TCP-only, peer-to-peer application, the client must support
<h2>General Guidance for Developers</h2>
+<h3>Application Design</h3>
<p>
SAM sessions (or inside I2P, tunnel pools or sets of tunnels) are designed to be long-lived.
Most applications will only need one session, created at startup and closed on exit.
@@ -273,7 +274,9 @@ Also, please ensure your application settings
will result in your users contributing more resources to the network than they consume.
I2P is a peer-to-peer network, and the network cannot survive if a popular application
drives the network into permanent congestion.
-</p><p>
+</p>
+<h3>Compatibility and Testing</h3>
+<p>
The Java I2P and i2pd router implementations are independent and have minor differences
in behavior, feature support, and defaults.
Please test your application with the latest version of both routers.
@@ -294,8 +297,20 @@ See below.
For more guidance to developers on ensuring your application uses only the resources it needs, please see
<a href="{{ site_url('docs/applications/embedding') }}">our guide to bundling I2P with your application</a>.
</p>
-
-
+<h3>Signature and Encryption Types</h3>
+<p>
+I2P supports multiple signature and encryption types.
+For backward compatibility, SAM defaults to old and inefficient types, so all clients should
+specify newer types.
+</p><p>
+The signature type is specified in the DEST GENERATE and SESSION CREATE (for transient) commands.
+All clients should set SIGNATURE_TYPE=7 (Ed25519).
+</p><p>
+The encryption type is specified in the SESSION CREATE command.
+Multiple encryption types are allowed.
+Clients should set either i2cp.leaseSetEncType=4 (for ECIES-X25519 only)
+or i2cp.leaseSetEncType=4,0 (for ECIES-X25519 and ElGamal, if compatibility is required).
+</p>
<h2>Version 3 Changes</h2>
diff --git a/i2p2www/pages/site/docs/applications/bittorrent.html b/i2p2www/pages/site/docs/applications/bittorrent.html
index 62cc4178b..d250a79c9 100644
--- a/i2p2www/pages/site/docs/applications/bittorrent.html
+++ b/i2p2www/pages/site/docs/applications/bittorrent.html
@@ -1,7 +1,7 @@
{% extends "global/layout.html" %}
{% block title %}{% trans %}Bittorrent over I2P{% endtrans %}{% endblock %}
-{% block lastupdated %}2023-01{% endblock %}
-{% block accuratefor %}0.9.57{% endblock %}
+{% block lastupdated %}2024-01{% endblock %}
+{% block accuratefor %}0.9.61{% endblock %}
{% block content %}
<p>{% trans -%}
@@ -58,6 +58,19 @@ For most low- to medium-bandwidth and low- to medium-connection counts, 3 is suf
Please specify the tunnel quantity in the SESSION CREATE message
to get consistent performance with the Java I2P and i2pd routers.
</p><p>
+I2P supports multiple signature and encryption types.
+For compatibility, I2P defaults to old and inefficient types, so all clients should
+specify newer types.
+</p><p>
+If using SAM, the signature type is specified in the DEST GENERATE and SESSION CREATE (for transient) commands.
+All clients should set SIGNATURE_TYPE=7 (Ed25519).
+</p><p>
+The encryption type is specified in the SAM SESSION CREATE command or in i2cp options.
+Multiple encryption types are allowed.
+Some trackers support ECIES-X25519, some support ElGamal, and some support both.
+Clients should set i2cp.leaseSetEncType=4,0 (for ECIES-X25519 and ElGamal)
+so that they may connect to both.
+</p><p>
DHT support requires SAM v3.3 PRIMARY and SUBSESSIONS for TCP and UDP over the same session.
This will require substantial development effort on the client side, unless the client is written in Java.
i2pd does not currently support SAM v3.3.
--
GitLab