Updates to 123, SAM, datagrams, I2CP

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

@@ -1,7 +1,7 @@
 {% extends "global/layout.html" %}
 {% block title %}{% trans %}Datagrams{% endtrans %}{% endblock %}
-{% block lastupdated %}{% trans %}August 2010{% endtrans %}{% endblock %}
+{% block lastupdated %}{% trans %}February 2019{% endtrans %}{% endblock %}
-{% block accuratefor %}0.8{% endblock %}
+{% block accuratefor %}0.9.39{% endblock %}
 {% block content %}
 <h2>{% trans %}Datagram Overview{% endtrans %}</h2>
 <p>{% trans i2cp=site_url('docs/protocol/i2cp') -%}
@@ -81,6 +81,12 @@ for this purpose. A common design pattern in client/server datagram applications
 use signed datagrams for a request which includes a nonce, and use a raw datagram
 for the reply, returning the nonce from the request.
 {%- endtrans %}</p>
+<p>Defaults:</p>
+<ul><li>
+PROTO_DATAGRAM = 17
+</li><li>
+PROTO_DATAGRAM_RAW = 18
+</li></ul>
 
 <p>{% trans i2psession='http://'+i2pconv('echelon.i2p/javadoc')+'/net/i2p/client/I2PSession.html',
 i2psessionmuxed='http://'+i2pconv('echelon.i2p/javadoc')+'/net/i2p/client/I2PSessionMuxedImpl.html' -%}

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

@@ -1,7 +1,7 @@
 {% extends "global/layout.html" %}
 {% block title %}SAM V3{% endblock %}
-{% block lastupdated %}March 2018{% endblock %}
+{% block lastupdated %}February 2019{% endblock %}
-{% block accuratefor %}0.9.34{% endblock %}
+{% block accuratefor %}0.9.39{% endblock %}
 {% block content %}
 <p>Specified below is a simple client protocol for interacting with I2P.
 </p>
@@ -343,11 +343,32 @@ sending and receiving messages/streams.
 The $privkey is the base 64 of the concatenation of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>
 followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_PrivateKey">Private Key</a>
 followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_SigningPrivateKey">Signing Private Key</a>,
+optionally followed by the <a href="{{ site_url('docs/spec/common-structures') }}#struct_OfflineSignature">Offline Signature</a>,
 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('echelon.i2p/javadoc') }}/net/i2p/data/PrivateKeyFile.html">Private Key File</a>.
 
 </p><p>
+If the signing private key is all zeros, the
+the <a href="{{ site_url('docs/spec/common-structures') }}#struct_OfflineSignature">Offline Signature</a> section follows.
+Offline signatures are only supported for STREAM and RAW sessions.
+Offline signatures may not be created with DESTINATION=TRANSIENT.
+The format of the offline signature section is:
+</p>
+
+<ol><li>
+  - Expires timestamp (4 bytes, big endian, seconds since epoch, rolls over in 2106)
+</li><li>
+  - Sig type of transient Signing Public Key (2 bytes, big endian)
+</li><li>
+  - Transient Signing Public key (length as specified by transient sig type)
+</li><li>
+  - Signature of above three fields by offline key (length as specified by destination sig type)
+</li><li>
+  - Transient Signing Private key (length as specified by transient sig type)
+</li></ol>
+
+<p>
 If the destination is specified as TRANSIENT, the SAM bridge creates a new destination.
 As of version 3.1 (I2P 0.9.14), if the destination is TRANSIENT, an optional parameter
 SIGNATURE_TYPE is supported. The SIGNATURE_TYPE value may be any name
@@ -385,10 +406,17 @@ If the creation was successful:
 The $privkey is the base 64 of the concatenation of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>
 followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_PrivateKey">Private Key</a>
 followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_SigningPrivateKey">Signing Private Key</a>,
+optionally followed by the <a href="{{ site_url('docs/spec/common-structures') }}#struct_OfflineSignature">Offline Signature</a>,
 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('echelon.i2p/javadoc') }}/net/i2p/data/PrivateKeyFile.html">Private Key File</a>.
 
+</p><p>
+If the SESSION CREATE contained a signing private key of all zeros and
+a <a href="{{ site_url('docs/spec/common-structures') }}#struct_OfflineSignature">Offline Signature</a> section,
+the SESSION STATUS reply will include the same data in the same format.
+See the SESSION CREATE section above for details.
+
 </p><p>
 If the nickname is already associated with a session:
 <pre>
@@ -828,10 +856,15 @@ CREATE command with PORT and HOST options:
  The $privkey is the base 64 of the concatenation of the <a href="{{ site_url('docs/spec/common-structures') }}#type_Destination">Destination</a>
    followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_PrivateKey">Private Key</a>
    followed by the <a href="{{ site_url('docs/spec/common-structures') }}#type_SigningPrivateKey">Signing Private Key</a>,
+   optionally followed by the <a href="{{ site_url('docs/spec/common-structures') }}#struct_OfflineSignature">Offline Signature</a>,
    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('echelon.i2p/javadoc') }}/net/i2p/data/PrivateKeyFile.html">Private Key File</a>.
 
+</p><p>
+Offline signatures are only supported for RAW datagrams.
+See the SESSION CREATE section above for details.
+
 </p><p>
  $host is the hostname or IP address of the datagram server to
      which SAM will forward datagrams. If not given, SAM takes the
@@ -1211,6 +1244,10 @@ The binary format is specified in <a href="http://{{ i2pconv('echelon.i2p/javado
 DEST GENERATE does not require that a session has been created first.
 </p>
 
+</p><p>
+DEST GENERATE cannot be used to create a destination with offline signatures.
+</p>
+
 
 <h4>PING/PONG (SAM 3.2 or higher)</h4>
 <p>

i2p2www/spec/common-structures.rst

@@ -27,7 +27,7 @@ Represents a non-negative integer.
 
 Contents
 ````````
-1 to 8 bytes in network byte order representing an unsigned integer
+1 to 8 bytes in network byte order (big endian) representing an unsigned integer.
 
 .. _type-Date:
 

i2p2www/spec/datagrams.rst

@@ -3,8 +3,8 @@ Datagram Specification
 ======================
 .. meta::
     :category: Protocols
-    :lastupdated: July 2014
+    :lastupdated: February 2019
-    :accuratefor: 0.9.14
+    :accuratefor: 0.9.39
 
 .. contents::
 
@@ -25,6 +25,8 @@ are also called "raw" datagrams.  Strictly speaking, they are not "datagrams"
 at all, they are just raw data.  They are not handled by the datagram API.
 However, SAM and the I2PTunnel classes support "raw datagrams".
 
+The standard I2CP protocol number for raw datagrams is PROTO_DATAGRAM_RAW (18).
+
 Format
 ------
 
@@ -55,6 +57,8 @@ Repliable Datagrams
 Repliable datagrams contain a 'from' address and a signature. These add at
 least 427 bytes of overhead.
 
+The standard I2CP protocol number for repliable datagrams is PROTO_DATAGRAM (17).
+
 Format
 ------
 
@@ -117,6 +121,9 @@ Notes
 
 * Signatures for types other than DSA_SHA1 were redefined in release 0.9.14.
 
+* The format does not support inclusion of an offline signature block
+  for LS2 (proposal 123). A new protocol with flags must be defined for that.
+
 
 References
 ==========

i2p2www/spec/i2cp.rst

@@ -389,6 +389,15 @@ Notes
 * The creation date must be within +/- 30 seconds of the current time when
   processed by the router, or the config will be rejected.
 
+Offline Signatures
+``````````````````
+* If the [Destination]_ is offline signed, the [Mapping]_ must contain
+  the three options i2cp.leaseSetOfflineExpiration, i2cp.leaseSetTransientPublicKey,
+  and i2cp.leaseSetOfflineSignature.
+  The [Signature]_ is then by the transient [SigningPrivateKey]_ and is verified
+  with the [SigningPublicKey]_ specified in i2cp.leaseSetTransientPublicKey.
+  See [I2CP-OPTIONS]_ for details.
+
 .. _struct-SessionId:
 
 Session ID
@@ -537,9 +546,9 @@ Contents
 4. [PrivateKey]_ list.
    One for each public key in the lease set, in the same order.
    (Not present for Meta LS2)
-   - Encryption type (2 bytes)
+   - Encryption type (2 byte [Integer]_)
-   - Encryption key length (2 bytes)
+   - Encryption key length (2 byte [Integer]_)
-   - Encryption key (number of bytes specified)
+   - Encryption [PrivateKey]_ (number of bytes specified)
 
 Notes
 `````

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-02-04
+    :lastupdated: 2019-02-07
     :status: Open
     :supercedes: 110, 120, 121, 122
 
@@ -219,8 +219,8 @@ Format
     Not actually in header, but part of data covered by signature.
     Take from field in Database Store Message.
   - Destination (387+ bytes)
-  - Published timestamp (4 bytes, seconds since epoch, rolls over in 2106)
+  - Published timestamp (4 bytes, big endian, seconds since epoch, rolls over in 2106)
-  - Expires (2 bytes) (offset from published timestamp in seconds, 18.2 hours max)
+  - Expires (2 bytes, big endian) (offset from published timestamp in seconds, 18.2 hours max)
   - Flags (2 bytes)
     Bit order: 15 14 ... 3 2 1 0
     Bit 0: If 0, no offline keys; if 1, offline keys
@@ -230,8 +230,8 @@ Format
            netdb for a new one.
     Bits 2-15: set to 0 for compatibility with future uses
   - If flag indicates offline keys, the offline signature section:
-    Expires timestamp (4 bytes, seconds since epoch, rolls over in 2106)
+    Expires timestamp (4 bytes, big endian, seconds since epoch, rolls over in 2106)
-    Transient sig type (2 bytes)
+    Transient sig type (2 bytes, big endian)
     Transient signing public key (length as implied by sig type)
     Signature of expires timestamp, transient sig type, and public key, by the destination public key,
     length as implied by destination public key sig type.
@@ -320,8 +320,8 @@ Format
   - Properties (Mapping as specified in common structures spec, 2 zero bytes if none)
   - Number of key sections to follow (1 byte, max TBD)
   - Key sections:
-    - Encryption type (2 bytes)
+    - Encryption type (2 bytes, big endian)
-    - Encryption key length (2 bytes)
+    - Encryption key length (2 bytes, big endian)
       This is explicit, so floodfills can parse LS2 with unknown encryption types.
     - Encryption key (number of bytes specified)
   - Number of lease2s (1 byte)
@@ -408,8 +408,6 @@ See also the ECIES proposals 144 and 145.
 Notes
 `````
 - 8-byte expiration in leases changed to 4 bytes.
-  Alternatives: 2-byte offset from the
-  published timestamp in seconds? Or 4-byte offset in milliseconds?
 
 - If we ever implement revocation, we can do it with an expires field of zero,
   or zero leases, or both. No need for a separate revocation key.
@@ -573,18 +571,18 @@ Type
     Take from field in Database Store Message.
 
 Blinded Public Key Sig Type
-    2 bytes
+    2 bytes, big endian
 
 Blinded Public Key
     Length as implied by sig type
 
 Published timestamp
-    4 bytes
+    4 bytes, big endian
 
     Seconds since epoch, rolls over in 2106
 
 Expires
-    2 bytes
+    2 bytes, big endian
 
     Offset from published timestamp in seconds, 18.2 hours max
 
@@ -601,12 +599,12 @@ Transient key data
     Present if flag indicates offline keys
 
     Expires timestamp
-        4 bytes
+        4 bytes, big endian
 
         Seconds since epoch, rolls over in 2106
 
     Transient sig type
-        2 bytes
+        2 bytes, big endian
 
     Transient signing public key
         Length as implied by sig type
@@ -619,7 +617,7 @@ Transient key data
         Verified with the blinded public key.
 
 lenOuterCiphertext
-    2 bytes
+    2 bytes, big endian
 
 outerCiphertext
     lenOuterCiphertext bytes
@@ -657,7 +655,7 @@ DH client auth data
         32 bytes
 
     clients
-        2 bytes
+        2 bytes, big endian
 
         Number of authClient entries to follow, 40 bytes each
 
@@ -678,7 +676,7 @@ PSK client auth data
         32 bytes
 
     clients
-        2 bytes
+        2 bytes, big endian
 
         Number of authClient entries to follow, 40 bytes each
 
@@ -1262,7 +1260,7 @@ Format
       TODO: Use a few bits to (optionally) indicate the type of the LS it is referencing.
       All zeros means don't know.
     - Cost (priority) (1 byte)
-    - Expires (4 bytes) (4 bytes, seconds since epoch, rolls over in 2106)
+    - Expires (4 bytes) (4 bytes, big endian, seconds since epoch, rolls over in 2106)
   - Number of revocations (1 byte) Maximum TBD
   - Revocations: Each revocation contains: (32 bytes)
     - Hash (32 bytes)
@@ -1318,7 +1316,7 @@ Format
   Standard LS2 Header as specified above
 
   Service Record Type-Specific Part
-  - Port (2 bytes) (0 if unspecified)
+  - Port (2 bytes, big endian) (0 if unspecified)
   - Hash of service name (32 bytes)
 
   Standard LS2 Signature:
@@ -1386,27 +1384,27 @@ Does NOT use the standard LS2 header specified above.
     Take from field in Database Store Message.
   - Hash of the service name (implicit, in the Database Store message)
   - Hash of the Creator (floodfill) (32 bytes)
-  - Published timestamp (8 bytes)
+  - Published timestamp (8 bytes, big endian)
 
   - Number of Short Service Records (1 byte)
   - List of Short Service Records:
     Each Short Service Record contains (90+ bytes)
     - Dest hash (32 bytes)
-    - Published timestamp (8 bytes)
+    - Published timestamp (8 bytes, big endian)
-    - Expires (4 bytes) (offset from published in ms)
+    - Expires (4 bytes, big endian) (offset from published in ms)
     - Flags (2 bytes)
-    - Port (2 bytes)
+    - Port (2 bytes, big endian)
-    - Sig length (2 bytes)
+    - Sig length (2 bytes, big endian)
     - Signature of dest (40+ bytes)
 
   - Number of Revocation Records (1 byte)
   - List of Revocation Records:
     Each Revocation Record contains (86+ bytes)
     - Dest hash (32 bytes)
-    - Published timestamp (8 bytes)
+    - Published timestamp (8 bytes, big endian)
     - Flags (2 bytes)
-    - Port (2 bytes)
+    - Port (2 bytes, big endian)
-    - Sig length (2 bytes)
+    - Sig length (2 bytes, big endian)
     - Signature of dest (40+ bytes)
 
   - Signature of floodfill (40+ bytes)
@@ -1554,7 +1552,7 @@ New options interpreted router-side, sent in SessionConfig Mapping:
                                   SessionConfig, to declare intent and check support.
                                   See proposals 144 and 145.
 
-  i2cp.leaseSetOfflineExpiration=nnn          The expiration of the offline signature, 4 bytes,
+  i2cp.leaseSetOfflineExpiration=nnn          The expiration of the offline signature, ASCII,
                                               seconds since the epoch.
 
   i2cp.leaseSetTransientPublicKey=[type:]b64  The base 64 of the transient private key,
@@ -1657,8 +1655,8 @@ Format
   LeaseSet: type specified above
   Encryption Private Keys: For each public key in the lease set, in the same order
                            (Not present for Meta LS2)
-                           - Encryption type (2 bytes)
+                           - Encryption type (2 bytes, big endian)
-                           - Encryption key length (2 bytes)
+                           - Encryption key length (2 bytes, big endian)
                            - Encryption key (number of bytes specified)
 
 
@@ -1743,7 +1741,7 @@ Changes
       1: LS 1
       3: LS 2
       7: Meta LS
-  6.  LeaseSet expiration (4 bytes, seconds since the epoch)
+  6.  LeaseSet expiration (4 bytes, big endian, seconds since the epoch)
       0 if unknown
   7.  Number of encryption types supported (1 byte)
       0 if unknown
@@ -1753,7 +1751,7 @@ Changes
       Bit order: 15 14 13...3210
       Bit 0: 1 for offline keys, 0 if not
       Bits 15-1: Unused, set to 0 for compatibility with future uses
-  11. If offline keys, the transient key sig type (2 bytes)
+  11. If offline keys, the transient key sig type (2 bytes, big endian)
   12. If offline keys, the transient public key (length as implied by sig type)
   13. If LeaseSet type is Meta (7), the number of meta entries to follow (1 byte)
   14. If LeaseSet type is Meta (7), the Meta Entries. Each entry contains: (40 bytes)
@@ -1763,7 +1761,7 @@ Changes
         TODO: Use a few bits to (optionally) indicate the type of the LS it is referencing.
         All zeros means don't know.
       - Cost (priority) (1 byte)
-      - Expires (4 bytes) (4 bytes, seconds since epoch, rolls over in 2106)
+      - Expires (4 bytes, big endian, seconds since epoch, rolls over in 2106)
 
 Notes
 `````
@@ -1806,8 +1804,8 @@ Changes
 
   If the signing private key is all zeros, the offline information section follows:
 
-  - Expires timestamp (4 bytes, seconds since epoch, rolls over in 2106)
+  - Expires timestamp (4 bytes, big endian, seconds since epoch, rolls over in 2106)
-  - Sig type of transient Signing Public Key (2 bytes)
+  - Sig type of transient Signing Public Key (2 bytes, big endian)
   - Transient Signing Public key (length as specified by transient sig type)
   - Signature of above three fields by offline key (length as specified by destination sig type)
   - Transient Signing Private key (length as specified by transient sig type)
@@ -1846,8 +1844,8 @@ Changes
   Option data:  Variable bytes
   Function:     Contains the offline signature section from LS2.
                 FROM_INCLUDED must also be set.
-                Expires timestamp (4 bytes, seconds since epoch, rolls over in 2106)
+                Expires timestamp (4 bytes, big endian, seconds since epoch, rolls over in 2106)
-                Transient sig type (2 bytes)
+                Transient sig type (2 bytes, big endian)
                 Transient signing public key (length as implied by sig type)
                 Signature of expires timestamp, transient sig type, and public key, by the destination public key,
                 length as implied by destination public key sig type.
@@ -1891,8 +1889,8 @@ Changes
     Bit 0: If 0, no offline keys; if 1, offline keys
     Bits 1-15: set to 0 for compatibility with future uses
   - If flag indicates offline keys, the offline signature section:
-    Expires timestamp (4 bytes, seconds since epoch, rolls over in 2106)
+    Expires timestamp (4 bytes, big endian, seconds since epoch, rolls over in 2106)
-    Transient sig type (2 bytes)
+    Transient sig type (2 bytes, big endian)
     Transient signing public key (length as implied by sig type)
     Signature of expires timestamp, transient sig type, and public key, by the destination public key,
     length as implied by destination public key sig type.
@@ -1907,17 +1905,55 @@ Notes
 - Any other options we should add now that we have flag bytes?
 
 
-SAM Changes Required
+SAM V3 Changes Required
-====================
+=======================
 
-TBD. See I2CP Host Reply Message section above.
+SAM must be enhanced to support offline signatures in the DESTINATION base 64.
+
+
+Changes
+-------
+
+::
+
+  Note that in the SESSION CREATE DESTINATION=$privkey,
+  the $privkey raw data (before base64 conversion)
+  may be optionally followed by the Offline Signature as specified in the
+  Common Structures Specification.
+
+  If the signing private key is all zeros, the offline information section follows:
+
+  - Expires timestamp (4 bytes, big endian, seconds since epoch, rolls over in 2106)
+  - Sig type of transient Signing Public Key (2 bytes, big endian)
+  - Transient Signing Public key (length as specified by transient sig type)
+  - Signature of above three fields by offline key (length as specified by destination sig type)
+  - Transient Signing Private key (length as specified by transient sig type)
+
+  Note that offline signatures are only supported for STREAM and RAW, not for DATAGRAM.
+  (until we define a new DATAGRAM protocol)
+
+  Note that the SESSION STATUS will return a Signing Private Key of all zeros and
+  the Offline Signature data exactly as supplied in the SESSION CREATE.
+
+  Note that DEST GENERATE and SESSION CREATE DESTINATION=TRANSIENT
+  may not be used to create an offline signed destination.
+
+
+
+Issues
+------
+- Bump version to 3.4, or leave it at 3.1/3.2/3.3 so it can be added
+  without requiring all the 3.2/3.3 stuff?
+- Other changes TBD. See I2CP Host Reply Message section above.
 
 
 
 BOB Changes Required
 ====================
 
-TBD. See I2CP Host Reply Message section above.
+BOB would have to be enhanced to support offline signatures and/or Meta LS.
+This is low priority and probably won't ever be specified or implemented.
+SAM V3 is the preferred interface.