Incorporate proposal 161 recommendations into the SAMv3 and Common Structures specs

i2p2www/pages/site/docs/api/samv3.html

@@ -1,7 +1,7 @@
 {% extends "global/layout.html" %}
 {% block title %}SAM V3{% endblock %}
-{% block lastupdated %}2022-12{% endblock %}
-{% block accuratefor %}2.0.0{% endblock %}
+{% block lastupdated %}2023-01{% endblock %}
+{% block accuratefor %}API 0.9.57{% 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,
@@ -617,6 +617,9 @@ optionally followed by the <a href="{{ site_url('docs/spec/common-structures') }
 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://{{ i2pconv('idk.i2p/javadoc-i2p') }}/net/i2p/data/PrivateKeyFile.html">Private Key File</a>.
+See additional notes about the
+<a href="{{ site_url('docs/spec/common-structures') }}#type_PrivateKey">Private Key</a>
+in the Destination Key Generation section below.
 
 </p><p>
 If the signing private key is all zeros, the
@@ -1595,6 +1598,22 @@ 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://{{ i2pconv('idk.i2p/javadoc-i2p') }}/net/i2p/data/PrivateKeyFile.html">Private Key File</a>.
 
+Notes about the 256-byte binary
+<a href="{{ site_url('docs/spec/common-structures') }}#type_PrivateKey">Private Key</a>:
+This field has been unused since version 0.6 (2005).
+SAM implementations may send random data or all zeros in this field;
+do not be alarmed about a string of AAAA in the base 64.
+Most applications will simply store the base 64 string and return it as-is in the SESSION CREATE, or
+decode to binary for storage, then encode again for SESSION CREATE.
+Applications may, however, decode the base 64, parse the binary following
+the PrivateKeyFile specification, discard the 256-byte private key portion,
+and then replace it with 256 bytes of random data or all zeros when re-encoding it for the SESSION CREATE.
+ALL other fields in the PrivateKeyFile specification must be preserved.
+This would save 256 bytes of file system storage but is probably not worth the trouble for most applications.
+
+See proposal 161 for addtional information and background.
+
+
 </p><p>
 DEST GENERATE does not require that a session has been created first.
 </p>

i2p2www/spec/common-structures.rst

@@ -3,8 +3,8 @@ Common structures Specification
 ===============================
 .. meta::
     :category: Design
-    :lastupdated: 2022-11
-    :accuratefor: 0.9.56
+    :lastupdated: 2023-01
+    :accuratefor: 0.9.57
 
 .. contents::
 
@@ -635,6 +635,50 @@ A PublicKey_ followed by a SigningPublicKey_ and then a Certificate_.
   total length: 387+ bytes
 {% endhighlight %}
 
+
+Padding Generation Guidelines
+`````````````````````````````````
+These guidelines were proposed in Proposal 161 and implemented in API version 0.9.57.
+These guidelines are backward-compatible with all versions since 0.6 (2005).
+See Proposal 161 for background and further information.
+
+For any currently-used combination of key types other than ElGamal + DSA-SHA1,
+padding will be present. Additionally, for destinations, the 256-byte
+public key field has been unused since version 0.6 (2005).
+
+Implementers should generate the random data for
+Destination public keys, and Destination and Router Identity padding,
+so that it is compressible in various I2P protocols while
+still being secure, and without having Base 64 representations appear to be corrupt or insecure.
+This provides most of the benefits of removing the padding fields without any
+disruptive protocol changes.
+
+Strictly speaking, the 32-byte signing public key alone (in both Destinations and Router Identities)
+and the 32-byte encryption public key (in Router Identities only) is a random number
+that provides all the entropy necessary for the SHA-256 hashes of these structures
+to be cryptographically strong and randomly distributed in the network database DHT.
+
+However, out of an abundance of caution, we recommend a minimum of 32 bytes of random data
+be used in the ElG public key field and padding. Additionally, if the fields were all zeros,
+Base 64 destinations would contain long runs of AAAA characters, which may cause alarm
+or confusion to users.
+
+Repeat the 32 bytes of random data as necessary so the full KeysAndCert structure is highly compressible
+in I2P protocols such as I2NP Database Store Message, Streaming SYN, SSU2 handshake, and repliable Datagrams.
+
+Examples:
+
+* A Router Identity with X25519 encryption type and Ed25519 signature type
+  will contain 10 copies (320 bytes) of the random data, for a savings of approximately 288 bytes when compressed.
+
+* A Destination with Ed25519 signature type
+  will contain 11 copies (352 bytes) of the random data, for a savings of approximately 320 bytes when compressed.
+
+Implementations must, of course, store the full 387+ byte structure because the SHA-256 hash of the structure
+covers the full contents.
+
+
+
 Notes
 `````
 * Do not assume that these are always 387 bytes! They are 387 bytes plus the
@@ -662,6 +706,9 @@ Contents
 ````````
 Identical to KeysAndCert.
 
+See KeysAndCert_ for guidelines on generating the random data for
+the padding field.
+
 Notes
 `````
 * The certificate for a RouterIdentity was always NULL until release 0.9.12.
@@ -694,12 +741,16 @@ for secure delivery.
 
 Contents
 ````````
-Identical to KeysAndCert_.
+Identical to KeysAndCert_, except that the public key is never used,
+and may contain random data instead of a valid ElGamal Public Key.
+
+See KeysAndCert_ for guidelines on generating the random data for
+the public key and padding fields.
 
 Notes
 `````
 * The public key of the destination was used for the old i2cp-to-i2cp
-  encryption which was disabled in version 0.6, it is currently unused except
+  encryption which was disabled in version 0.6 (2005), it is currently unused except
   for the IV for LeaseSet encryption, which is deprecated. The public key in
   the LeaseSet is used instead.
 

i2p2www/spec/proposals/161-ri-dest-padding.rst

@@ -5,13 +5,19 @@ RI and Destination Padding
     :author: zzz
     :created: 2022-09-28
     :thread: http://zzz.i2p/topics/3279
-    :lastupdated: 2022-12-19
+    :lastupdated: 2023-01-02
     :status: Open
     :target: 0.9.57
 
 .. contents::
 
 
+Status
+========
+
+Implemented in 0.9.57.
+Leaving this proposal open so we may enhance and discuss the ideas in the "Future Planning" section.
+
 
 Overview
 ========