Copy proposal 149 into naming spec

i2p2www/pages/site/docs/naming.html

@@ -1,7 +1,7 @@
 {% extends "global/layout.html" %}
 {% block title %}{% trans %}Naming and Addressbook{% endtrans %}{% endblock %}
-{% block lastupdated %}{% trans %}June 2018{% endtrans %}{% endblock %}
+{% block lastupdated %}{% trans %}June 2019{% endtrans %}{% endblock %}
-{% block accuratefor %}0.9.34{% endblock %}
+{% block accuratefor %}0.9.41{% endblock %}
 {% block content %}
 <h2 id="overview">{% trans %}Overview{% endtrans %}</h2>
 
@@ -469,7 +469,7 @@ Example: <code>ukeu3k5oycgaauneqgtnvselmt4yemvoilkln7jpvamvfx7dnkdq.b32.i2p</cod
 In Tor, the address is 16 characters (80 bits), or half of the SHA-1 hash.
 I2P uses 52 characters (256 bits) to represent the full SHA-256 hash.
 The form is {52 chars}.b32.i2p.
-Tor has recently published a
+Tor has a
 <a href="https://blog.torproject.org/blog/tor-weekly-news-%E2%80%94-december-4th-2013">proposal</a>
 to convert to an identical format of {52 chars}.onion for their hidden services.
 Base32 is implemented in the naming service, which queries the
@@ -487,3 +487,137 @@ name does not immediately resolve. I2PTunnel will fail, for example, if
 the name does not resolve to a destination.
 {%- endtrans %}</p>
 {% endblock %}
+
+
+<h2 id="newbase32">Extended Base32 Names</h2>
+<p>
+Extended base 32 names were introduced in release 0.9.40
+to support encrypted lease sets.
+Addresses for encrypted leasesets are identified by 56 or more encoded characters,
+not including the ".b32.i2p"
+(35 or more decoded bytes), compared to 52 characters (32 bytes) for traditional base 32 addresses.
+See proposals 123 and 149 for additional information.
+</p><p>
+Standard Base 32 ("b32") addresses contain the hash of the destination.
+This will not work for encrypted ls2 (proposal 123).
+</p><p>
+You can't use a traditional base 32 address for an encrypted LS2 (proposal 123),
+as it contains only the hash of the destination. It does not provide the non-blinded public key.
+Clients must know the destination's public key, sig type,
+the blinded sig type, and an optional secret or private key
+to fetch and decrypt the leaseset.
+Therefore, a base 32 address alone is insufficient.
+The client needs either the full destination (which contains the public key),
+or the public key by itself.
+If the client has the full destination in an address book, and the address book
+supports reverse lookup by hash, then the public key may be retrieved.
+</p><p>
+So we need a new format that puts the public key instead of the hash into
+a base32 address. This format must also contain the signature type of the
+public key, and the signature type of the blinding scheme.
+</p><p>
+This section documents a new b32 format for these addresses.
+While we have referred to this new format during discussions
+as a "b33" address, the actual new format retains the usual ".b32.i2p" suffix.
+</p><p>
+
+<h3>Creation and encoding</h3>
+
+<p>
+Construct a hostname of {56+ chars}.b32.i2p (35+ chars in binary) as follows.
+First, construct the binary data to be base 32 encoded:
+</p>
+<pre>
+  flag (1 byte)
+    bit 0: 0 for one-byte sigtypes, 1 for two-byte sigtypes
+    bit 1: 0 for no secret, 1 if secret is required
+    bit 2: 0 for no per-client auth,
+           1 if client private key is required
+    bits 7-3: Unused, set to 0
+
+  public key sigtype (1 or 2 bytes as indicated in flags)
+    If 1 byte, the upper byte is assumed zero
+
+  blinded key sigtype (1 or 2 bytes as indicated in flags)
+    If 1 byte, the upper byte is assumed zero
+
+  public key
+    Number of bytes as implied by sigtype
+</pre>
+
+<p>
+Post-processing and checksum:
+</p>
+<pre>
+  Construct the binary data as above.
+  Treat checksum as little-endian.
+  Calculate checksum = CRC-32(data[3:end])
+  data[0] ^= (byte) checksum
+  data[1] ^= (byte) (checksum >> 8)
+  data[2] ^= (byte) (checksum >> 16)
+
+  hostname = Base32.encode(data) || ".b32.i2p"
+</pre>
+<p>
+Any unused bits at the end of the b32 must be 0.
+There are no unused bits for a standard 56 character (35 byte) address.
+</p>
+
+
+<h3>Decoding and Verification</h3>
+<pre>
+  Strip the ".b32.i2p" from the hostname
+  data = Base32.decode(hostname)
+  Calculate checksum = CRC-32(data[3:end])
+  Treat checksum as little-endian.
+  flags = data[0] ^ (byte) checksum
+  if 1 byte sigtypes:
+    pubkey sigtype = data[1] ^ (byte) (checksum >> 8)
+    blinded sigtype = data[2] ^ (byte) (checksum >> 16)
+  else (2 byte sigtypes) :
+    pubkey sigtype = data[1] ^ ((byte) (checksum >> 8)) || data[2] ^ ((byte) (checksum >> 16))
+    blinded sigtype = data[3] || data[4]
+  parse the remainder based on the flags to get the public key
+</pre>
+
+<h3>Secret and Private Key Bits</h3>
+<p>
+The secret and private key bits are used to indicate to clients, proxies, or other
+client-side code that the secret and/or private key will be required to decrypt the
+leaseset. Particular implementations may prompt the user to supply the
+required data, or reject connection attempts if the required data is missing.
+</p>
+
+<h3>Notes</h3>
+
+<ul><li>
+XORing first 3 bytes with the hash provides a limited checksum capability,
+and ensures that all base32 chars at the beginning are randomized.
+Only a few flag and sigtype combinations are valid, so any typo is likely to create an invalid combination and will be rejected.
+</li><li>
+In the usual case (1 byte sigtypes, no secret, no per-client auth),
+the hostname will be {56 chars}.b32.i2p, decoding to 35 bytes, same as Tor.
+</li><li>
+Tor 2-byte checksum has a 1/64K false negative rate. With 3 bytes, minus a few ignored bytes,
+ours is approaching 1 in a million, since most flag/sigtype combinations are invalid.
+</li><li>
+Adler-32 is a poor choice for small inputs, and for detecting small changes.
+We use CRC-32 instead. CRC-32 is fast and is widely available.
+</li><li>
+While outside the scope of this specification, routers and/or clients must remember and cache
+(probably persistently) the mapping of public key to destination, and vice versa.
+</li><li>
+Distinguish old from new flavors by length. Old b32 addresses are always {52 chars}.b32.i2p. New ones are {56+ chars}.b32.i2p
+</li><li>
+Tor discussion thread <a href="https://lists.torproject.org/pipermail/tor-dev/2017-January/011816.html">is here</a>
+</li><li>
+Don't expect 2-byte sigtypes to ever happen, we're only up to 13. No need to implement now.
+</li><li>
+New format can be used in jump links (and served by jump servers) if desired, just like b32.
+</li><li>
+Any secret, private key, or public key longer than 32 bytes would
+exceed the DNS max label length of 63 chars. Browsers probably do not care.
+</li><li>
+No backward compatibility issues. Longer b32 addresses will fail to be converted
+to 32-byte hashes in old software.
+</li></ul>

i2p2www/spec/encryptedleaseset.rst

@@ -3,7 +3,7 @@ Encrypted LeaseSet Specification
 ================================
 .. meta::
     :category: Protocols
-    :lastupdated: May 2019
+    :lastupdated: June 2019
     :accuratefor: 0.9.41
 
 .. contents::
@@ -784,24 +784,27 @@ supports reverse lookup by hash, then the public key may be retrieved.
 So we need a new format that puts the public key instead of the hash into
 a base32 address. This format must also contain the signature type of the
 public key, and the signature type of the blinding scheme.
-The total requirements are 32 + 2 + 2 = 36 bytes, requiring 58 characters in base 32.
+The total requirements are 32 + 3 = 35 bytes, requiring 56 characters in base 32,
+or more for longer public key types.
 
 .. raw:: html
 
   {% highlight lang='text' %}
-data = 32 byte pubkey || 2 byte unblinded sigtype || 2 byte blinded sigtype
+data = ((1 byte flags || 1 byte unblinded sigtype || 1 byte blinded sigtype) XOR checksum) || 32 byte pubkey
   address = Base32Encode(data) || ".b32.i2p"
 {% endhighlight %}
 
 We use the same ".b32.i2p" suffix as for traditional base 32 addresses.
-Addresses for encrypted leasesets are identified by the 58 encoded characters
+Addresses for encrypted leasesets are identified by the 56 encoded characters
-(36 decoded bytes), compared to 52 characters (32 bytes) for traditional base 32 addresses.
+(35 decoded bytes), compared to 52 characters (32 bytes) for traditional base 32 addresses.
 The five unused bits at the end of b32 must be 0.
 
 You can't use an encrypted LS2 for bittorrent, because of compact announce replies which are 32 bytes.
 The 32 bytes contain only the hash. There is no room for an indication that the
 leaseset is encrypted, or the signature types.
 
+See the naming specification or proposal 149 for more information on the new format.
+
 
 
 Encrypted LS with Offline Keys

i2p2www/spec/proposals/123-new-netdb-entries.rst

@@ -5,7 +5,7 @@ New netDB Entries
     :author: zzz, str4d, orignal
     :created: 2016-01-16
     :thread: http://zzz.i2p/topics/2051
-    :lastupdated: 2019-05-29
+    :lastupdated: 2019-06-03
     :status: Open
     :supercedes: 110, 120, 121, 122
 
@@ -48,6 +48,9 @@ The following proposals are somewhat related:
 - 145 ECIES-P256
 - 146 Red25519
 - 148 EdDSA-BLAKE2b-Ed25519
+- 149 B32 for Encrypted LS2
+- 150 Garlic Farm Protocol
+- 151 ECDSA Blinding
 
 
 Proposal

i2p2www/spec/proposals/149-b32-encrypted-ls2.rst

@@ -5,7 +5,7 @@ B32 for Encrypted LS2
     :author: zzz
     :created: 2019-03-13
     :thread: http://zzz.i2p/topics/2682
-    :lastupdated: 2019-05-27
+    :lastupdated: 2019-06-03
     :status: Open
 
 .. contents::
@@ -174,7 +174,6 @@ Notes
 - Distinguish old from new flavors by length. Old b32 addresses are always {52 chars}.b32.i2p. New ones are {56+ chars}.b32.i2p
 - Tor discussion thread: https://lists.torproject.org/pipermail/tor-dev/2017-January/011816.html
 - Don't expect 2-byte sigtypes to ever happen, we're only up to 13. No need to implement now.
-- Hostnames with secret and/or privkeys are for private sharing only and are low-security.
 - New format can be used in jump links (and served by jump servers) if desired, just like b32.