proposals 142, 143

i2p2www/spec/proposals/142-new-crypto-template.rst

@@ -0,0 +1,107 @@
+================================
+New Encryption Proposal Template
+================================
+.. meta::
+    :author: zzz
+    :created: 2018-01-11
+    :thread: http://zzz.i2p/topics/2499
+    :lastupdated: 2017-01-20
+    :status: Meta
+
+.. contents::
+
+
+Overview
+========
+
+This document describes important issues to consider when proposing
+a replacement or addition to our ElGamal asymmetric encryption.
+
+This is an informational document.
+
+
+Motivation
+==========
+
+ElGamal is old and slow, and there are better alternatives.
+However, there are several issues that must be addressed before we can add or change to any new algorithm.
+This document highlights these unresolved issues.
+
+
+
+Background Research
+===================
+
+Anybody proposing new crypto must first be familiar with the following documents:
+
+- Proposal 111 NTCP2 https://geti2p.net/spec/proposals/111-ntcp-2
+- Proposal 123 LS2 https://geti2p.net/spec/proposals/123-new-netdb-entries
+- Proposal 136 experimental sig types https://geti2p.net/spec/proposals/136-experimental-sigtypes
+- Proposal 137 optional sig types https://geti2p.net/spec/proposals/137-optional-sigtypes
+- Discussion threads here for each of the above proposals, linked within
+- http://zzz.i2p/topics/2494 2018 proposal priorities
+- http://zzz.i2p/topics/2418 ECIES proposal
+- http://zzz.i2p/topics/1768 new asymmetric crypto overview
+- Low-level crypto overview https://geti2p.net/spec/cryptography
+
+
+Asymmetric Crypto Uses
+======================
+
+As a review, we use ElGamal for:
+
+1) Tunnel Build messages (key is in RouterIdentity)
+
+2) Router-to-router encryption of netdb and other i2np msgs (Key is in RouterIdentity)
+
+3) Client End-to-end ElGamal+AES/SessionTag (key is in LeaseSet, the Destination key is unused)
+
+4) Ephemeral DH for NTCP and SSU
+
+
+Design
+======
+
+Any proposal to replace ElGamal with something else must provide the following details.
+
+
+
+Specification
+=============
+
+Any proposal for new asymmetric crypto must fully specify the following things.
+
+
+
+1. General
+----------
+
+Answer the following questions in your proposal. Note that this may need to be a separate proposal from the specifics in 2) below, as it may conflict with existing proposals 111, 123, 136, 137, or others.
+
+- Which of the above cases 1-4 do you propose to use the new crypto for?
+- If for 1) or 2) (router), Where does the public key go, in the RouterIdentity or the RouterInfo props? Do you intend to use the crypto type in the key cert? Completely specify. Justify your decision either way.
+- If for 3) (client), do you intend to store the public key in the destination and use the crypto type in the key cert (as in the ECIES proposal), or store it in LS2 (as in proposal 123), or something else? Completely specify, and justify your decision.
+- For all uses, how will support be advertised? If for 3), does it go in the LS2, or somewhere else? If for 1) and 2), is it similar to proposals 136 and/or 137? Completely specify, and justify your decisions. Will probably need a separate proposal for this.
+- Completely specify how and why this is backward compatible, and fully specify a migration plan.
+- Which unimplemented proposals are prerequisites for your proposal?
+
+
+2. Specific crypto type
+-----------------------
+
+Answer the following questions in your proposal:
+
+- General crypto info, specific curves/parameters, completely justify your choice. Provide links to specs and other info.
+- Speed test results compared to ElG and other alternatives if applicable. Include encrypt, decrypt, and keygen.
+- Library availability in C++ and Java (both OpenJDK, BouncyCastle, and 3rd party)
+  For 3rd party or non-Java, provide links and licenses
+- Proposed crypto type number(s) (experimental range or not)
+
+
+
+
+Notes
+=====
+
+
+

i2p2www/spec/proposals/143-build-message-options.rst

@@ -0,0 +1,97 @@
+============================
+Tunnel Build Message Options
+============================
+.. meta::
+    :author: zzz
+    :created: 2018-01-14
+    :thread: http://zzz.i2p/topics/2500
+    :lastupdated: 2017-01-20
+    :status: Open
+
+.. contents::
+
+
+Overview
+========
+
+ref: http://i2p-projekt.i2p/spec/tunnel-creation
+
+Add a flexible, extensible mechanism for options in the I2NP Tunnel Build Records
+which are contained in the Tunnel Build and Tunnel Build Reply messages.
+
+
+Motivation
+==========
+
+
+There are a few tentative, undocumented proposals coming to set options or configuration in the Tunnel Build Message,
+so the creator of the tunnel may pass some parameters to each tunnel hop.
+
+There are 29 spare bytes in the TBM. We want to keep flexibility for future enhancements, but also use the space wisely.
+Using the 'mapping' construction would use at least 6 bytes per option ("1a=1b;").
+Defining more option fields rigidly could cause problems later.
+
+This document proposes a new, flexible options mapping scheme.
+
+
+
+Design
+======
+
+We need an option representation that is compact and yet flexible, so that we may fit multiple
+options, of varying length, into 29 bytes.
+These options are not yet defined, and are not required to be at this time.
+Don't use the "mapping" structure (which encodes a Java Properties object), it is too wasteful.
+Use a number to indicate each option and length, which results in a compact yet flexible encoding.
+Options must be registered by number in our specifications, but we will also reserve a range for experimental options.
+
+
+Specification
+=============
+
+Preliminary - several alternatives are described below.
+
+This would be present only if bit 5 in the flags (byte 184) is set to 1.
+
+Each option is a two byte option number and length, followed by length bytes of option value.
+
+Options start at byte 193 and continue through at most the last byte 221.
+
+Option number/length:
+
+Two bytes. Bits 15-4 are the 12-bit option number, 1 - 4095.
+Bits 3-0 are the number of option value bytes to follow, 0 - 15.
+A boolean option could have zero value bytes.
+We will maintain a registry of option numbers in our specs, and also define a range for experimental options.
+
+The option value is 0 to 15 bytes, to be interpreted by whatever needs that option. Unknown option numbers should be ignored.
+
+The options are concluded with an option number/length of 0/0, that is two 0 bytes.
+ The remainder of the 29 bytes, if any, should be filled with random padding, as usual.
+
+This encoding gives us space for 14 0-byte options, or 9 1-byte options, or 7 2-byte options.
+An alternative would be to use only one byte for the option number/length,
+perhaps with 5 bits for option number (32 max and 3 bits for length (7 max).
+This would increase capacity to 28 0-byte options, 14 1-byte options, or 9 two-byte options.
+We could also make it variable, where a 5-bit option number of 31 means read 8 more bits for the option number.
+
+If the tunnel hop needs to return options to the creator, we may use the same format in the tunnel build reply message,
+prefixed by some magic number of several bytes (since we don't have a defined flag byte to indicate that options are present).
+There are 495 spare bytes in the TBRM.
+
+
+Notes
+=====
+
+These changes are to the Tunnel Build Records, and so may be used in all Build Message flavors -
+Tunnel Build Request, Variable Tunnel Build Request, Tunnel Build Reply, and Variable Tunnel Build Reply.
+
+
+
+Migration
+=========
+
+The unused space in the Tunnel Build Records are filled with random data and currently ignored.
+The space can be converted to contain options without migration issues.
+In the build message, the presence of options is indicated in the flags byte.
+In the build reply message, the presence of options is indicated by a multi-byte magic number.