blocklist news feed spec

i2p2www/spec/proposals/129-blocklist-newsxml.rst

@@ -5,7 +5,7 @@ Blocklist in News Feed
     :author: zzz
     :created: 2016-11-23
     :thread: http://zzz.i2p/topics/2191
-    :lastupdated: 2016-11-23
+    :lastupdated: 2016-11-24
     :status: Open
 
 .. contents::
@@ -14,7 +14,8 @@ Blocklist in News Feed
 Overview
 ========
 
-This proposal is to distribute blocklist updates in the news file.
+This proposal is to distribute blocklist updates in the news file,
+which is distributed in signed su3 format.
 
 
 Motivation
@@ -29,20 +30,28 @@ uses the news subscription now.
 Design
 ======
 
-Add a new section to the news.xml.
+Add a new section to the news.xml file.
 Allow blocking by IP or router hash.
+The section will have its own time stamp.
+Allow for unblocking of previously-blocked entries.
+
 Include a signature of the section, to be specified.
+The signature will cover the time stamp.
 The signature must be verifed on import.
+The signer will be specified and may be different from the su3 signer.
+Routers may use a different trust list for the blocklist.
 
 
 Specification
 =============
 
-To be added to the router update specification page.
+Now on the router update specification page.
 
 Entries are either a literal IPv4 or IPv6 address,
 or a 44-character base64-encoded router hash.
+IPv6 addresses may be in abbreviated format (containing "::").
 Support for blocking with a net mask, e.g. x.y.0.0/16, is optional.
+Support for host names is optional.
 
 
 Migration
@@ -51,6 +60,12 @@ Migration
 Routers that don't support this will ignore the new XML section.
 
 
+Scheduled For
+=============
+
+0.9.28
+
+
 See Also
 ========
 

i2p2www/spec/updates.rst

@@ -2,8 +2,8 @@
 Software Update Specification
 =============================
 .. meta::
-    :lastupdated: April 2016
-    :accuratefor: 0.9.25
+    :lastupdated: November 2016
+    :accuratefor: 0.9.28
 
 .. contents::
 
@@ -421,6 +421,9 @@ The following <feed> elements are used:
     <i2p:revocations>
         Certificate revocations. See below.
 
+    <i2p:blocklist>
+        Blocklist data. See below.
+
     <updated>
         Required
 
@@ -535,8 +538,7 @@ following attributes and entities:
 **Atom <i2p:revocations> Details:**
 
 This entity is optional and there is at most one <i2p:revocations> entity in the
-feed. This feature is scheduled for implementation in release 0.9.26. The
-specification below is preliminary and subject to change.
+feed. This feature is supported as of release 0.9.26.
 
 The <i2p:revocations> entity contains one or more <i2p:crl> entities. The
 <i2p:crl> entity contains the following attributes:
@@ -553,16 +555,72 @@ The <i2p:revocations> entity contains one or more <i2p:crl> entities. The
 
     id (attribute)
         Required
+
         A unique id for the creator of this CRL.
 
     (entity content)
         Required
+
         A standard base 64 encoded Certificate Revocation List (CRL) with
         newlines, starting with the line '-----BEGIN X509 CRL-----' and
         ending with the line '-----END X509 CRL-----'. See [RFC-5280]_
         for more information on CRLs.
 
 
+**Atom <i2p:blocklist> Details:**
+
+This entity is optional and there is at most one <i2p:blocklist> entity in the
+feed. This feature is scheduled for implementation in release 0.9.28. The
+specification below is preliminary and subject to change.
+
+The <i2p:blocklist> entity contains one or more <i2p:block> or <i2p:unblock> entities,
+an "updated" entity, and "signer" and "sig" attributes:
+
+    signer (attribute)
+        Required
+
+        A unique id (UTF-8) for the public key used to sign this blocklist.
+
+    sig (attribute)
+        Required
+
+        A signature in the format code:b64sig, where code is the ASCII signature
+        type number, and b64sig is the base 64 encoded signature (I2P alphabet).
+        See below for specification of data to be signed.
+
+    <updated>
+        Required
+
+        Timestamp for the blocklist (conforming to [RFC-4287]_ (Atom) section 3.3
+        and [RFC-3339]_.
+
+        The date also may be in truncated format yyyy-mm-dd (without the 'T');
+        this is the "full-date" format in [RFC-3339]_. In this format the time
+        is assumed to be 00:00:00 UTC for any processing.
+
+    <i2p:block>
+        Optional, multiple entities are allowed
+
+        A single entry, either a literal IPv4 or IPv6 address,
+        or a 44-character base 64 router hash (I2P alphabet).
+        IPv6 addresses may be in abbreviated format (containing "::").
+        Support for entries with a netmask, e.g. x.y.0.0/16, is optional.
+        Support for host names is optional.
+
+    <i2p:unblock>
+        Optional, multiple entities are allowed
+
+        Same format as <i2p:block>.
+
+
+Signature specification: To generate the data to be signed or verified,
+concatenate the following data in ASCII encoding:
+The updated string followed by a newline (ASCII 0x0a),
+then each block entry in the order received with a newline after each,
+then each unblock entry in the order received with a newline after each.
+
+
+
 Future Work
 ===========