NetDb updates for 0.9.38

i2p2www/pages/site/docs/how/network-database.html

@@ -1,7 +1,7 @@
 {% extends "global/layout.html" %}
 {% block title %}{% trans %}The Network Database{% endtrans %}{% endblock %}
-{% block lastupdated %}{% trans %}April 2018{% endtrans %}{% endblock %}
-{% block accuratefor %}0.9.32{% endblock %}
+{% block lastupdated %}{% trans %}January 2019{% endtrans %}{% endblock %}
+{% block accuratefor %}0.9.38{% endblock %}
 {% block content %}
 <h2>{% trans %}Overview{% endtrans %}</h2>
 
@@ -29,8 +29,8 @@ a structure called the "RouterInfo", which is distributed with the SHA256 of the
 as the key. The structure itself contains:
 {%- endtrans %}</p>
 <ul>
-  <li>{% trans %}The router's identity (a 2048bit ElGamal encryption key, a signing key, and a certificate){% endtrans %}</li>
-  <li>{% trans %}The contact addresses at which it can be reached (e.g. TCP: example.org port 4108){% endtrans %}</li>
+  <li>{% trans %}The router's identity (an encryption key, a signing key, and a certificate){% endtrans %}</li>
+  <li>{% trans %}The contact addresses at which it can be reached{% endtrans %}</li>
   <li>{% trans %}When this was published{% endtrans %}</li>
   <li>{% trans %}A set of arbitrary text options{% endtrans %}</li>
   <li>{% trans %}The signature of the above, generated by the identity's signing key{% endtrans %}</li>
@@ -178,6 +178,10 @@ be frequently republished to them.
 <p>{% trans -%}
 RouterInfos are periodically written to disk so that they are available after a restart.
 {%- endtrans %}</p>
+<p>{% trans -%}
+It may be desirable to persistently store Meta LeaseSets with long expirations.
+This is implementation-dependent.
+{%- endtrans %}</p>
 
 
 <h3>{% trans %}See Also{% endtrans %}</h3>
@@ -189,6 +193,9 @@ RouterInfos are periodically written to disk so that they are available after a
   <a href="http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/router/RouterInfo.html">{% trans %}RouterInfo Javadoc{% endtrans %}</a>
 </p>
 
+
+
+
 <h2 id="leaseSet">LeaseSet</h2>
 
 <p>{% trans -%}
@@ -210,7 +217,7 @@ the key derived from the SHA256 of the destination.
 In addition to these leases, the LeaseSet includes:
 {%- endtrans %}</p>
   <ul>
-    <li>{% trans %}The destination itself (a 2048bit ElGamal encryption key, a signing key and a certificate){% endtrans %}</li>
+    <li>{% trans %}The destination itself (an encryption key, a signing key and a certificate){% endtrans %}</li>
     <li>{% trans %}Additional encryption public key: used for end-to-end encryption of garlic messages{% endtrans %}</li>
     <li>{% trans %}Additional signing public key: intended for LeaseSet revocation, but is currently unused.{% endtrans %}</li>
     <li>{% trans %}Signature of all the LeaseSet data, to make sure the Destination published the LeaseSet.{% endtrans %}</li>
@@ -227,6 +234,11 @@ In addition to these leases, the LeaseSet includes:
   <a href="http://{{ i2pconv('echelon.i2p/javadoc') }}/net/i2p/data/LeaseSet.html">{% trans %}LeaseSet Javadoc{% endtrans %}</a>
 </p>
 
+<p>{% trans -%}
+As of release 0.9.38, three new types of LeaseSets are defined;
+LeaseSet2, MetaLeaseSet, and EncryptedLeaseSet. See below.
+{%- endtrans %}</p>
+
 
 <h3 id="unpublished">{% trans %}Unpublished LeaseSets{% endtrans %}</h3>
 <p>{% trans -%}
@@ -247,8 +259,39 @@ Revocations are not fully implemented, and it is unclear if they have any practi
 This is the only planned use for that signing key, so it is currently unused.
 {%- endtrans %}</p>
 
+
+<h3 id="encrypted">LeaseSet2 (LS2)</h3>
+<p>{% trans -%}
+As of release 0.9.38, floodfills support a new LeaseSet2 structure.
+This structure is very similar to the old LeaseSet structure, and serves the same purpose.
+The new structure provides the flexibility required to support new
+encryption types, multiple encryption types, options, offline signing keys,
+and other features.
+See proposal 123 for details.
+{%- endtrans %}</p>
+
+
+<h3 id="encrypted">Meta LeaseSet (LS2)</h3>
+<p>{% trans -%}
+As of release 0.9.38, floodfills support a new Meta LeaseSet structure.
+This structure provides a tree-like structure in the DHT, to refer to other LeaseSets.
+Using Meta LeaseSets, a site may implement large multihomed services, where several
+different Destinations are used to provide a common service.
+The entries in a Meta LeaseSet are Destinations or other Meta LeaseSets,
+and may have long expirations, up to 18.2 hours.
+Using this facility, it should be possible to run hundreds or thousands of Destinations hosting a common service.
+See proposal 123 for details.
+{%- endtrans %}</p>
+
+
+
 <h3 id="encrypted">{% trans %}Encrypted LeaseSets{% endtrans %}</h3>
 <p>{% trans -%}
+This section describes the old, insecure method of encrypting
+LeaseSets using a fixed symmetric key.
+See below for the LS2 version of Encrypted LeaseSets.
+{%- endtrans %}</p>
+<p>{% trans -%}
 In an <i>encrypted</i> LeaseSet, all Leases are encrypted with a separate key.
 The leases may only be decoded, and thus the destination may only be contacted,
 by those with the key.
@@ -257,10 +300,26 @@ Encrypted LeaseSets are not widely used, and it is a topic for future work to
 research whether the user interface and implementation of encrypted LeaseSets could be improved.
 {%- endtrans %}</p>
 
+
+<h3 id="encrypted">{% trans %}Encrypted LeaseSets{% endtrans %}(LS2)</h3>
+<p>{% trans -%}
+As of release 0.9.38, floodfills support a new, EncryptedLeaseSet structure.
+The Destination is hidden, and only a blinded public key and an expiration
+are visible to the floodfill.
+Only those that have the full Destination may decrypt the structure.
+The structure is stored at a DHT location based on the hash of the blinded public key,
+not the hash of the Destination.
+See proposal 123 for details.
+{%- endtrans %}</p>
+
+
 <h3>{% trans %}LeaseSet Expiration{% endtrans %}</h3>
 <p>{% trans -%}
-All Leases (tunnels) are valid for 10 minutes; therefore, a LeaseSet expires
-10 minutes after the earliest creation time of all its Leases.
+For regular LeaseSets, the expiration is the time of the latest expiration of its leases.
+For the new LeaseSet2 data structures, the expiration is specified in the header.
+For LeaseSet2, the expiration should match the latest expiration of its leases.
+For EncryptedLeaseSet and MetaLeaseSet, the expiration may vary,
+and maximum expiration may be enforced, to be determined.
 {%- endtrans %}</p>
 
 <h3>{% trans %}LeaseSet Persistent Storage{% endtrans %}</h3>