From 852677ac91f00ccd0748cc0e42fdb84b6d66c644 Mon Sep 17 00:00:00 2001 From: zzz Date: Sun, 17 Apr 2016 20:42:58 +0000 Subject: [PATCH] add subscription proposal --- i2p2www/spec/proposals/125-subscription.rst | 178 ++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 i2p2www/spec/proposals/125-subscription.rst diff --git a/i2p2www/spec/proposals/125-subscription.rst b/i2p2www/spec/proposals/125-subscription.rst new file mode 100644 index 00000000..82d387bb --- /dev/null +++ b/i2p2www/spec/proposals/125-subscription.rst @@ -0,0 +1,178 @@ +===================================== +New Addressbook Subscription Protocol +===================================== +.. meta:: + :author: zzz + :created: 2014-09-15 + :thread: http://zzz.i2p/topics/1704 + :lastupdated: 2016-04-17 + :status: Draft V3 + +.. contents:: + + +Proposal version 3 +2016-04-17 + +Overview +======== + + +The exising protocol has one type of line: + +foo.i2p=b64destination + + + +This proposal adds two new types: + +1) Add and Change commands: + +foo.i2p=b64destination#!key1=val1#key2=val2 ... + + +2) Remove commands: + +#!key1=val1#key2=val2 ... + + + + +All commands must contain a signature key/value "sig=b64signature" where the signature for the other data, using the destination signing key. +All commands except the "Add" command must contain a "action=command" key/value. +For commands including an old and new destination, there must also be a oldsig=b64signature, and either oldname, olddest, or both. + +Keys may be in any order. Duplicate keys are not allowed. All keys and values are case-sensitive. + +To generate a byte stream to create or verify the signature, serialize as follows: + (Output encoding is UTF-8) + - Remove the "sig" key + - If verifying with oldsig, also remove the "oldsig" key + - For Add or Change commands: + - output name=b64dest (name must be lower-case) + - If any keys remain, output "#!" + - Sort the options by UTF-8 key, fail if duplicate keys + - For each key/value, output key=value, + followed by (if not the last key/value) a '#' + - Do not output a newline + + +In an Add or Change command, the public key for verification is in the destination to be added or changed. + +In some add or edit commands, there may be an additional destination referenced, +for example when adding an alias, or changing a destination or host name. +In that case, there must be a second signature included and both should be verified. +The second signature is the "inner" signature and is signed and verified first (excluding the "outer" signature). + The client should take any additional action necessary to verify and accept changes. + +oldsig is always the "inner" signature. Sign and verify without the 'oldsig' or 'sig' keys present. +sig is always the "outer" signature. Sign and verify with the 'oldsig' key present but not the 'sig' key. + + +Ordering: A feed is not necessarily in-order or complete. +For example, a change command may be on a line before an add command, or without an add command. + + + +DETAILS +======= + + +Common keys +----------- + + Required in all commands: + - sig: b64 signature, using signing key from the destination + + References to a second hostname and/or destination; + - oldname: a second hostname (new or changed) + - olddest: a second b64 destination (new or changed) + - oldsig: a second b64 signature, using signing key from nolddest + + Other common keys: + - action: a command + - name: the hostname, only present if not preceded by name=dest + - dest: the b64 destination, only present if not preceded by name=dest + - date: in seconds since epoch + - expires: in seconds since epoch + + + +Commands +-------- + +For compatibility with older clients, most commands are preceded by +name=dest, as noted below. For changes, these are always the new values. +Any old values are included in the key/value section. + + +Listed keys are required. +All commands may contain additional key/value items not defined here. + +Add hostname: + Preceded by name=dest? YES, this is the new host name and destination. + action is NOT included, it is implied. + sig: signature + Example: name=dest#!sig=b64sig + +Change hostname: + Preceded by name=dest? YES, this is the new host name and old destination. + action: changename + oldname: the old hostname, to be replaced + sig: signature + Example: name=dest#!action=changename#oldname=oldhostname#sig=b64sig + +Change destination: + Preceded by name=dest? YES, this is the old host name and new destination. + action: changedest + olddest: the old dest, to be replaced + oldsig: signature using olddest + sig: signature + Example: name=dest#!action=changedest#olddest=oldb64dest#oldsig=b64sig#sig=b64sig + +Add hostname alias: + Preceded by name=dest? YES, this is the new (alias) host name and old destination. + action: addname + oldname: the old hostname + sig: signature + Example: name=dest#!action=addname#oldname=oldhostname#sig=b64sig + +Add destination alias: (Used for crypto upgrade) + Preceded by name=dest? YES, this is the old host name and new (alternate) destination. + action: adddest + olddest: the old dest + oldsig: signature using olddest + sig: signature using dest + Example: name=dest#!action=adddest#olddest=oldb64dest#oldsig=b64sig#sig=b64sig + +Add subdomain: + Preceded by name=dest? YES, this is the new host subdomain name and destination. + action: addsubdomain + oldname: the old hostname, unchanged + olddest: the old dest, unchanged + oldsig: signature using olddest + sig: signature using dest + Example: name=dest#!action=addsubdomain#oldname=oldhostname#olddest=oldb64dest#oldsig=b64sig#sig=b64sig + +Update metadata: + Preceded by name=dest? YES, this is the old host name and destination. + action: update + sig: signature + (add any updated keys here) + Example: name=dest#!action=update#k1=v1#k2=v2#sig=b64sig + +Remove hostname: + Preceded by name=dest? NO, these are specified in the options + action: remove + name: the hostname + dest: the destination + sig: signature + Example: #!action=removeall#name=hostname#dest=b64destsig=b64sig + +Remove all with this destination: + Preceded by name=dest? NO, these are specified in the options + action: removeall + name: the old hostname, advisory only + dest: the old dest, all with this dest are removed + sig: signature + Example: #!action=removeall#name=hostname#dest=b64destsig=b64sig