diff --git a/i2p2www/pages/site/docs/how/cryptography.html b/i2p2www/pages/site/docs/how/cryptography.html deleted file mode 100644 index e009dc31..00000000 --- a/i2p2www/pages/site/docs/how/cryptography.html +++ /dev/null @@ -1,523 +0,0 @@ -{% extends "global/layout.html" %} -{% block title %}{% trans %}Low-level Cryptography Details{% endtrans %}{% endblock %} -{% block lastupdated %}{% trans %}December 2014{% endtrans %}{% endblock %} -{% block accuratefor %}0.9.17{% endblock %} -{% block content %} -

{% trans -%} -This page specifies the low-level details of the cryptography in I2P. -{%- endtrans %}

- -

{% trans elgamalaes=site_url('docs/how/elgamal-aes') -%} -There are a handful of cryptographic algorithms in use within I2P, but we have -reduced them to a bare minimum to deal with our needs - one symmetric algorithm -one asymmetric algorithm, one signing algorithm, and one hashing algorithm. However, -we do combine them in some particular ways to provide message integrity (rather than -relying on a MAC). In addition, as much as we hate doing anything new in regards to -cryptography, we can't seem to find a reference discussing (or even naming) the -technique used in ElGamal/AES+SessionTag (but we're sure others have done it). -{%- endtrans %}

- -

{% trans %}ElGamal encryption{% endtrans %}

- -

{% trans %} -ElGamal is used for asymmetric encryption. -ElGamal is used in several places in I2P: -{%- endtrans %}

- - -

{% trans -%} -We use common primes for 2048 ElGamal encryption and decryption, as given by IETF RFC-3526. -We currently only use ElGamal to encrypt the IV and session key in a single block, followed by the -AES encrypted payload using that key and IV. -{%- endtrans %}

- -

{% trans -%} -The unencrypted ElGamal contains: -{%- endtrans %}

-{% highlight lang='dataspec' %} - +----+----+----+----+----+----+----+----+ - |nonz| H(data) | - +----+ + - | | - + + - | | - + + - | | - + +----+----+----+----+----+----+----+ - | | data... - +----+----+----+-// -{% endhighlight %} - -

{% trans -%} -The H(data) is the SHA256 of the data that is encrypted in the ElGamal block, -and is preceded by a nonzero byte. -This byte could be random, but as implemented it is always 0xFF. -It could possibly be used for flags in the future. -The data encrypted in the block may be up to 222 bytes long. -As the encrypted data may contain a substantial number of zeros if the -cleartext is smaller than 222 bytes, it is recommended that higher layers pad -the cleartext to 222 bytes with random data. -Total length: typically 255 bytes. -{%- endtrans %}

- -

{% trans -%} -The encrypted ElGamal contains: -{%- endtrans %}

-

-{% highlight lang='dataspec' %} - +----+----+----+----+----+----+----+----+ - | zero padding... | | - +----+----+----+-//-+----+ + - | | - + + - | ElG encrypted part 1 | - ~ ~ - | | - + +----+----+----+----+----+----+----+ - | | zero padding... | | - +----+----+----+----+-//-+----+ + - | | - + + - | ElG encrypted part 2 | - ~ ~ - | | - + +----+----+----+----+----+----+ - | + - +----+----+ -{% endhighlight %} - -

{% trans -%} -Each encrypted part is prepended with zeros to a size of exactly 257 bytes. -Total length: 514 bytes. -In typical usage, higher layers pad the cleartext data to 222 bytes, -resulting in an unencrypted block of 255 bytes. -This is encoded as two 256-byte encrypted parts, -and there is a single byte of zero padding before each part at this layer. -{%- endtrans %}

- -

{% trans url='https://github.com/i2p/i2p.i2p/tree/master/core/java/src/net/i2p/crypto/ElGamalEngine.java' -%} -See the ElGamal code. -{%- endtrans %}

- -

{% trans -%} -The shared prime is the -[Oakley prime for 2048 bit keys] -{%- endtrans %}

-
- 2^2048 - 2^1984 - 1 + 2^64 * { [2^1918 pi] + 124476 }
-
-

{% trans -%} -or as a hexadecimal value: -{%- endtrans %}

-
- FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1
- 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD
- EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245
- E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED
- EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE45B3D
- C2007CB8 A163BF05 98DA4836 1C55D39A 69163FA8 FD24CF5F
- 83655D23 DCA3AD96 1C62F356 208552BB 9ED52907 7096966D
- 670C354E 4ABC9804 F1746C08 CA18217C 32905E46 2E36CE3B
- E39E772C 180E8603 9B2783A2 EC07A28F B5C55DF0 6F4C52C9
- DE2BCBF6 95581718 3995497C EA956AE5 15D22618 98FA0510
- 15728E5A 8AACAA68 FFFFFFFF FFFFFFFF
-
-

{% trans -%} -Using 2 as the generator. -{%- endtrans %}

- -

{% trans %}Short Exponent{% endtrans %}

-

{% trans commonstructures=site_url('docs/spec/common-structures') -%} -While the standard exponent size is 2048 bits (256 bytes) and the I2P -PrivateKey -is a full 256 bytes, in some cases -we use the short exponent size of 226 bits (28.25 bytes). -{%- endtrans %}

- -

{% trans pdf='http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.14.5952&rep=rep1&type=pdf', -benchmarks=site_url('misc/benchmarks'), -oldbenchmarks='http://www.eskimo.com/~weidai/benchmarks.html' -%} -This should be safe for use with the Oakley primes, per -On Diffie-Hellman Key Agreement with Short Exponents - van Oorschot, Weiner -at EuroCrypt 96, and crypto++'s benchmarks. -Benchmarks originally at this link, now dead, -rescued from the wayback machine, dated Apr 23, 2008. -{%- endtrans %}

- -

{% trans book='http://www.springerlink.com/content/2jry7cftp5bpdghm/', -fulltext='http://books.google.com/books?id=cXyiNZ2_Pa0C&lpg=PA173&ots=PNIz3dWe4g&pg=PA173#v=onepage&q&f=false', -thread='http://groups.google.com/group/sci.crypt/browse_thread/thread/1855a5efa7416677/339fa2f945cc9ba0#339fa2f945cc9ba0' -%} -Also, Koshiba & Kurosawa: Short Exponent Diffie-Hellman Problems (PKC 2004, LNCS 2947, pp. 173-186) -(full text on Google Books) apparently supports this, according to -this sci.crypt thread. -The remainder of the PrivateKey is padded with zeroes. -{%- endtrans %}

- -

{% trans -%} -Prior to release 0.9.8, all routers used the short exponent. -As of release 0.9.8, 64-bit x86 routers use a full 2048-bit exponent. -Other routers continue to use the short exponent due to concerns about processor load. -The transition to a longer exponent for these platforms is a topic for further study. -{%- endtrans %}

- -

{% trans %}Obsolescence{% endtrans %}

-

{% trans -%} -The vulnerability of the network to an ElGamal attack and the impact of transitioning to a longer bit length is to be studied. -It may be quite difficult to make any change backward-compatible. -{%- endtrans %}

- - -

AES

- -

{% trans -%} -AES is used for symmetric encryption, in several cases: -{%- endtrans %}

- - - -

{% trans rfc2313='http://tools.ietf.org/html/rfc2313', -code1='https://github.com/i2p/i2p.i2p/tree/master/core/java/src/net/i2p/crypto/CryptixAESEngine.java', -code2='https://github.com/i2p/i2p.i2p/tree/master/core/java/src/net/i2p/crypto/CryptixRijndael_Algorithm.java', -code3='https://github.com/i2p/i2p.i2p/tree/master/core/java/src/net/i2p/crypto/ElGamalAESEngine.java' -%} -We use AES with 256 bit keys and 128 bit blocks in CBC mode. -The padding used is specified in IETF RFC-2313 (PKCS#5 1.5, section 8.1 (for block type 02)). -In this case, padding exists of pseudorandomly generated octets to match 16 byte blocks. -Specifically, see [the CBC code] and the Cryptix AES -[implementation], as well as the padding, found in the -ElGamalAESEngine.getPadding function. -{%- endtrans %}

- - - - -

{% trans %}Obsolescence{% endtrans %}

-

{% trans -%} -The vulnerability of the network to an AES attack and the impact of transitioning to a longer bit length is to be studied. -It may be quite difficult to make any change backward-compatible. -{%- endtrans %}

- -

{% trans %}References{% endtrans %}

- - - -

{% trans %}Digital Signatures{% endtrans %}

- -

{% trans -%} -DSA is the default signature algorithm, but we are in the process of migrating to more secure algorithms. See below. -{%- endtrans %}

- -

DSA

- -

{% trans code='https://github.com/i2p/i2p.i2p/tree/master/core/java/src/net/i2p/crypto/DSAEngine.java' -%} -Signatures are generated and verified with 1024 bit DSA (L=1024, N=160), as implemented in -[DSAEngine]. -DSA was chosen because it is much faster for signatures than ElGamal. -{%- endtrans %}

- -

SEED

- -

160 bit

- -
- 86108236b8526e296e923a4015b4282845b572cc
-
- -

Counter

- -
- 33
-
-

-

DSA prime (p)

- -

1024 bit

- -

-

- 9C05B2AA 960D9B97 B8931963 C9CC9E8C 3026E9B8 ED92FAD0
- A69CC886 D5BF8015 FCADAE31 A0AD18FA B3F01B00 A358DE23
- 7655C496 4AFAA2B3 37E96AD3 16B9FB1C C564B5AE C5B69A9F
- F6C3E454 8707FEF8 503D91DD 8602E867 E6D35D22 35C1869C
- E2479C3B 9D5401DE 04E0727F B33D6511 285D4CF2 9538D9E3
- B6051F5B 22CC1C93
-
-

-

DSA quotient (q)

- -

-

- A5DFC28F EF4CA1E2 86744CD8 EED9D29D 684046B7
-
-

-

DSA generator (g)

- -

1024 bit

- -

-

- 0C1F4D27 D40093B4 29E962D7 223824E0 BBC47E7C 832A3923
- 6FC683AF 84889581 075FF908 2ED32353 D4374D73 01CDA1D2
- 3C431F46 98599DDA 02451824 FF369752 593647CC 3DDC197D
- E985E43D 136CDCFC 6BD5409C D2F45082 1142A5E6 F8EB1C3A
- B5D0484B 8129FCF1 7BCE4F7F 33321C3C B3DBB14A 905E7B2B
- 3E93BE47 08CBCC82
-
- -

{% trans commonstructures=site_url('docs/spec/common-structures') -%} -The Signing Public Key is 1024 bits. -The Signing Private Key is 160 bits. -{%- endtrans %}

- - -

{% trans %}Obsolescence{% endtrans %}

-

{% trans pdf='http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf' -%} -NIST 800-57 -recommends a minimum of (L=2048, N=224) for usage beyond 2010. -This may be mitigated somewhat by the "cryptoperiod", or lifespan of a given key. -{%- endtrans %}

- -

{% trans -%} -The prime number was chosen in 2003, -and the person that chose the number (TheCrypto) is currently no longer an I2P developer. -As such, we do not know if the prime chosen is a 'strong prime'. -If a larger prime is chosen for future purposes, this should be a strong prime, and we will document the construction process. -{%- endtrans %}

- - -

{% trans %}References{% endtrans %}

- - - - -

{% trans %}New Signature Algorithms{% endtrans %}

-

{% trans -%} -As of release 0.9.12, the router supports additional signature algorithms that are more secure than 1024-bit DSA. -The first usage is for Destinations; support for Router Identities was added in release 0.9.16. -Support for migrating existing Destinations from old to new signatures will be added in a future release. -Signature type is encoded in the Destination and Router Identity, so that new signature algorithms -or curves may be added at any time. -The current supported signature types are as follows: -{%- endtrans %}

- - -

ECDSA

- -

{% trans -%} -ECDSA uses the standard NIST curves and standard SHA-2 hashes. -We will migrate new destinations to ECDSA-SHA256-P256 in the 0.9.16 - 0.9.19 release time frame. -Usage for Router Identities is supported as of release 0.9.16 and migration may occur in early 2015. -{%- endtrans %}

- - -

RSA

- -

{% trans -%} -Standard RSA PKCS#1 v1.5 (RFC 2313) with the public exponent F4 = 65537. -RSA is now used for signing all out-of-band trusted content, including router updates, reseeding, plugins, and news. -The signatures are embedded in the "su3" format documented on the router updates page. -4096-bit keys are recommended and used by all known signers. -RSA is not used, or planned for use, in any in-network Destinations or Router Identities. -{%- endtrans %}

- - -

EdDSA 25519

- -

{% trans -%} -Standard EdDSA using curve 25519 and standard 512-bit SHA-2 hashes. -Supported as of release 0.9.15. -Migration for Destinations and Router Identities is scheduled for mid-2015. -{%- endtrans %}

- - - -

SHA256

- -

{% trans code='https://github.com/i2p/i2p.i2p/tree/master/core/java/src/net/i2p/crypto/SHA256Generator.java' -%} -Hashes within I2P are plain old SHA256, as implemented in -[SHA256Generator] -{%- endtrans %}

- -

{% trans %}Obsolescence{% endtrans %}

-

{% trans -%} -The vulnerability of the network to a SHA-256 attack and the impact of transitioning to a longer hash is to be studied. -It may be quite difficult to make any change backward-compatible. -{%- endtrans %}

- -

{% trans %}References{% endtrans %}

- - -

{% trans %}Transports{% endtrans %}

-

{% trans -%} -At the lowest protocol layer, -point-to-point inter-router communication is protected by the transport layer security. -Both transports use 256 byte (2048 bit) Diffie-Hellman key exchange -using -the same shared prime and generator as specified above for ElGamal, -followed by symmetric AES encryption as described above. -This provides -perfect forward secrecy -on the transport links. -{%- endtrans %}

- -

{% trans %}NTCP connections{% endtrans %}

- -

{% trans elgamalaes=site_url('docs/how/elgamal-aes') -%} -NTCP connections are negotiated with a 2048 Diffie-Hellman implementation, -using the router's identity to proceed with a station to station agreement, followed by -some encrypted protocol specific fields, with all subsequent data encrypted with AES -(as above). -The primary reason to do the DH negotiation instead of using ElGamalAES+SessionTag is that it provides '(perfect) forward secrecy', while ElGamalAES+SessionTag does not. -{%- endtrans %}

- -

{% trans -%} -In order to migrate to a more standardized implementation (TLS/SSL or even SSH), the following issues must be addressed: -{%- endtrans %}

-
    -
  1. {% trans -%} -Can we somehow reestablish sessions securely (ala session tags) or do we need to do full negotiation each time? -{%- endtrans %}
    2. -
  2. {% trans -%} -Can we simplify/avoid the x509 or other certificate formats and use our own RouterInfo structure (which -contains the ElGamal and DSA keys)? -{%- endtrans %}
    3. -
-

{% trans ntcp=site_url('docs/transport/ntcp') -%} -See the NTCP specification for details. -{%- endtrans %}

- -

{% trans %}UDP connections{% endtrans %}

-

{% trans -%} -SSU (the UDP transport) encrypts each packet with AES256/CBC with both an explicit IV and MAC -(HMAC-MD5-128) after agreeing upon an ephemeral session key through a 2048 bit -Diffie-Hellman exchange, station-to-station authentication with the other -router's DSA key, plus each network message has their own hash for local integrity -checking. -{%- endtrans %}

- -

{% trans ssu=site_url('docs/transport/ssu') -%} -See the SSU specification for details. -{%- endtrans %}

- -

{% trans statusnotes=get_url('blog_post', slug='2005/07/05/status') -%} -WARNING - I2P's HMAC-MD5-128 used in SSU is apparently non-standard. -Apparently, an early version of SSU used HMAC-SHA256, and then it was switched -to MD5-128 for performance reasons, but left the 32-byte buffer size intact. -See HMACGenerator.java and -the 2005-07-05 status notes -for details. -{%- endtrans %}

- - -

{% trans %}References{% endtrans %}

- - -{% endblock %} diff --git a/i2p2www/spec/cryptography.rst b/i2p2www/spec/cryptography.rst new file mode 100644 index 00000000..2ec521a7 --- /dev/null +++ b/i2p2www/spec/cryptography.rst @@ -0,0 +1,545 @@ +==================================== +Low-level Cryptography Specification +==================================== +.. meta:: + :lastupdated: December 2014 + :accuratefor: 0.9.17 + + +Overview +======== + +This page specifies the low-level details of the cryptography in I2P. + +There are a handful of cryptographic algorithms in use within I2P, but we have +reduced them to a bare minimum to deal with our needs - one symmetric algorithm +one asymmetric algorithm, one signing algorithm, and one hashing algorithm. +However, we do combine them in some particular ways to provide message +integrity (rather than relying on a MAC). In addition, as much as we hate +doing anything new in regards to cryptography, we can't seem to find a +reference discussing (or even naming) the technique used in +ElGamal/AES+SessionTag [ELG-AES]_ (but we're sure others have done it). + + +Asymmetric encryption +===================== + +ElGamal +------- + +ElGamal is used for asymmetric encryption. ElGamal is used in several places +in I2P: + +* To encrypt router-to-router [TunnelBuild]_ messages + +* For end-to-end (destination-to-destination) encryption as a part of + ElGamal/AES+SessionTag [ELG-AES]_ using the encryption key in the [LeaseSet]_ + +* For encryption of some netDb stores and queries sent to floodfill routers + [NETDB-DELIVERY]_ as a part of ElGamal/AES+SessionTag [ELG-AES]_ + (destination-to-router or router-to-router). + +We use common primes for 2048 ElGamal encryption and decryption, as given by +IETF [RFC-3526]_. We currently only use ElGamal to encrypt the IV and session +key in a single block, followed by the AES encrypted payload using that key and +IV. + +The unencrypted ElGamal contains: + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + |nonz| H(data) | + +----+ + + | | + + + + | | + + + + | | + + +----+----+----+----+----+----+----+ + | | data... + +----+----+----+-// +{% endhighlight %} + +The H(data) is the SHA256 of the data that is encrypted in the ElGamal block, +and is preceded by a nonzero byte. This byte could be random, but as +implemented it is always 0xFF. It could possibly be used for flags in the +future. The data encrypted in the block may be up to 222 bytes long. As the +encrypted data may contain a substantial number of zeros if the cleartext is +smaller than 222 bytes, it is recommended that higher layers pad the cleartext +to 222 bytes with random data. Total length: typically 255 bytes. + +The encrypted ElGamal contains: + +.. raw:: html + + {% highlight lang='dataspec' %} ++----+----+----+----+----+----+----+----+ + | zero padding... | | + +----+----+----+-//-+----+ + + | | + + + + | ElG encrypted part 1 | + ~ ~ + | | + + +----+----+----+----+----+----+----+ + | | zero padding... | | + +----+----+----+----+-//-+----+ + + | | + + + + | ElG encrypted part 2 | + ~ ~ + | | + + +----+----+----+----+----+----+ + | + + +----+----+ +{% endhighlight %} + +Each encrypted part is prepended with zeros to a size of exactly 257 bytes. +Total length: 514 bytes. In typical usage, higher layers pad the cleartext +data to 222 bytes, resulting in an unencrypted block of 255 bytes. This is +encoded as two 256-byte encrypted parts, and there is a single byte of zero +padding before each part at this layer. + +See the ElGamal code [ElGamalEngine]_. + +The shared prime is the Oakley prime for 2048 bit keys [RFC-3526-S3]_:: + + 2^2048 - 2^1984 - 1 + 2^64 * { [2^1918 pi] + 124476 } + +or as a hexadecimal value:: + + FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 + 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD + EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 + E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED + EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE45B3D + C2007CB8 A163BF05 98DA4836 1C55D39A 69163FA8 FD24CF5F + 83655D23 DCA3AD96 1C62F356 208552BB 9ED52907 7096966D + 670C354E 4ABC9804 F1746C08 CA18217C 32905E46 2E36CE3B + E39E772C 180E8603 9B2783A2 EC07A28F B5C55DF0 6F4C52C9 + DE2BCBF6 95581718 3995497C EA956AE5 15D22618 98FA0510 + 15728E5A 8AACAA68 FFFFFFFF FFFFFFFF + +Using 2 as the generator. + +.. _exponent: + +Short Exponent +`````````````` +While the standard exponent size is 2048 bits (256 bytes) and the I2P +[PrivateKey]_ is a full 256 bytes, in some cases we use the short exponent size +of 226 bits (28.25 bytes). This should be safe for use with the Oakley primes +[vanOorschot1996]_ [BENCHMARKS]_. + +Also, [Koshiba2004]_ apparently supports this, according to this sci.crypt +thread [SCI.CRYPT]_. The remainder of the PrivateKey is padded with zeroes. + +Prior to release 0.9.8, all routers used the short exponent. As of release +0.9.8, 64-bit x86 routers use a full 2048-bit exponent. Other routers continue +to use the short exponent due to concerns about processor load. The transition +to a longer exponent for these platforms is a topic for further study. + +Obsolescence +```````````` +The vulnerability of the network to an ElGamal attack and the impact of +transitioning to a longer bit length is to be studied. It may be quite +difficult to make any change backward-compatible. + + +Symmetric encryption +==================== + +AES +--- + +AES is used for symmetric encryption, in several cases: + +* For transport encryption (see section "`Transports`_") after DH key exchange + +* For end-to-end (destination-to-destination) encryption as a part of + ElGamal/AES+SessionTag [ELG-AES]_ + +* For encryption of some netDb stores and queries sent to floodfill routers + [NETDB-DELIVERY]_ as a part of ElGamal/AES+SessionTag [ELG-AES]_ + (destination-to-router or router-to-router). + +* For encryption of periodic tunnel test messages [TUNNEL-TESTING]_ sent from + the router to itself, through its own tunnels. + +We use AES with 256 bit keys and 128 bit blocks in CBC mode. The padding used +is specified in IETF [RFC-2313]_ (PKCS#5 1.5, section 8.1 (for block type 02)). +In this case, padding exists of pseudorandomly generated octets to match 16 +byte blocks. Specifically, see the CBC code [CryptixAESEngine]_ and the +Cryptix AES implementation [CryptixRijndael_Algorithm]_, as well as the +padding, found in the ElGamalAESEngine.getPadding function [ElGamalAESEngine]_. + +.. Believe it or not, we don't do this any more. If we ever did. safeEncode() and safeDecode() are unused. + +.. In all cases, we know the size of the data to be sent, and we AES encrypt the following: + +.. .. raw:: html + +.. % highlight lang='dataspec' %} +.. +----+----+----+----+----+----+----+----+ + | H(data) | + + + + | | + + + + | | + + + + | | + +----+----+----+----+----+----+----+----+ + | size | data ... | + +----+----+----+----+ + + | | + ~ ~ + | | + + + + | | + + +----//---+----+ + | | | + +----+----+----//---+----+ + + | Padding to 16 bytes | + +----+----+----+----+----+----+----+----+ + +.. H(data) :: 32-byte SHA-256 `Hash` of the data + +.. . size :: 4-byte `Integer`, number of data bytes to follow + +.. . data :: payload + +.. . padding :: random data, to a multiple of 16 bytes +.. % endhighlight %} + +.. After the data comes an application-specified number of randomly generated + padding bytes. This application-specified number is rounded up to a multiple + of 16. The entire segment (from H(data) through the end of the random bytes) + is AES encrypted (256 bit CBC w/ PKCS#5). + +.. This code is implemented in the safeEncrypt and safeDecrypt methods of + AESEngine but it is unused. + + +Obsolescence +```````````` +The vulnerability of the network to an AES attack and the impact of +transitioning to a longer bit length is to be studied. It may be quite +difficult to make any change backward-compatible. + +References +`````````` +* [STATUS-AES]_ + + +.. _sig: + +Signatures +========== + +DSA is the default signature algorithm, but we are in the process of migrating +to more secure algorithms. See below. + +DSA +--- + +Signatures are generated and verified with 1024 bit [DSA]_ (L=1024, N=160), as +implemented in [DSAEngine]_. DSA was chosen because it is much faster for +signatures than ElGamal. + +SEED +```` +160 bit:: + + 86108236b8526e296e923a4015b4282845b572cc + +Counter +``````` +:: + + 33 + +DSA prime (p) +````````````` +1024 bit:: + + 9C05B2AA 960D9B97 B8931963 C9CC9E8C 3026E9B8 ED92FAD0 + A69CC886 D5BF8015 FCADAE31 A0AD18FA B3F01B00 A358DE23 + 7655C496 4AFAA2B3 37E96AD3 16B9FB1C C564B5AE C5B69A9F + F6C3E454 8707FEF8 503D91DD 8602E867 E6D35D22 35C1869C + E2479C3B 9D5401DE 04E0727F B33D6511 285D4CF2 9538D9E3 + B6051F5B 22CC1C93 + +DSA quotient (q) +```````````````` +:: + + A5DFC28F EF4CA1E2 86744CD8 EED9D29D 684046B7 + +DSA generator (g) +````````````````` +1024 bit:: + + 0C1F4D27 D40093B4 29E962D7 223824E0 BBC47E7C 832A3923 + 6FC683AF 84889581 075FF908 2ED32353 D4374D73 01CDA1D2 + 3C431F46 98599DDA 02451824 FF369752 593647CC 3DDC197D + E985E43D 136CDCFC 6BD5409C D2F45082 1142A5E6 F8EB1C3A + B5D0484B 8129FCF1 7BCE4F7F 33321C3C B3DBB14A 905E7B2B + 3E93BE47 08CBCC82 + +The [SigningPublicKey]_ is 1024 bits. The [SigningPrivateKey]_ is 160 bits. + +Obsolescence +```````````` +[NIST-800-57]_ recommends a minimum of (L=2048, N=224) for usage beyond 2010. +This may be mitigated somewhat by the "cryptoperiod", or lifespan of a given +key. + +The prime number was chosen in 2003 [CHOOSING-CONSTANTS]_, and the person that +chose the number (TheCrypto) is currently no longer an I2P developer. As such, +we do not know if the prime chosen is a 'strong prime'. If a larger prime is +chosen for future purposes, this should be a strong prime, and we will document +the construction process. + +References +`````````` +* [MEETING-51]_ +* [MEETING-52]_ + + +New Signature Algorithms +======================== + +As of release 0.9.12, the router supports additional signature algorithms that +are more secure than 1024-bit DSA. The first usage is for Destinations; +support for Router Identities was added in release 0.9.16. Support for +migrating existing Destinations from old to new signatures will be added in a +future release. Signature type is encoded in the Destination and Router +Identity, so that new signature algorithms or curves may be added at any time. +The current supported signature types are as follows: + +* DSA-SHA1 +* ECDSA-SHA256-P256 +* ECDSA-SHA384-P384 +* ECDSA-SHA512-P521 +* RSA-SHA256-2048 +* RSA-SHA384-3072 +* RSA-SHA512-4096 +* EdDSA-SHA512-Ed25519 (as of release 0.9.15) + +ECDSA +----- + +ECDSA uses the standard NIST curves and standard SHA-2 hashes. + +We will migrate new destinations to ECDSA-SHA256-P256 in the 0.9.16 - 0.9.19 +release time frame. Usage for Router Identities is supported as of release +0.9.16 and migration may occur in early 2015. + +RSA +--- + +Standard RSA PKCS#1 v1.5 (RFC 2313) with the public exponent F4 = 65537. + +RSA is now used for signing all out-of-band trusted content, including router +updates, reseeding, plugins, and news. The signatures are embedded in the +"su3" format [UPDATES]_. 4096-bit keys are recommended and used by all known +signers. RSA is not used, or planned for use, in any in-network Destinations +or Router Identities. + +EdDSA 25519 +----------- + +Standard EdDSA using curve 25519 and standard 512-bit SHA-2 hashes. + +Supported as of release 0.9.15. + +Migration for Destinations and Router Identities is scheduled for mid-2015. + + +Hashes +====== + +SHA256 +------ + +Hashes within I2P are plain old SHA256, as implemented in [SHA256Generator]_. + +Obsolescence +```````````` +The vulnerability of the network to a SHA-256 attack and the impact of +transitioning to a longer hash is to be studied. It may be quite difficult to +make any change backward-compatible. + +References +`````````` +* [SHA-2]_ + + +Transports +========== + +At the lowest protocol layer, point-to-point inter-router communication is +protected by the transport layer security. Both transports use 256 byte (2048 +bit) Diffie-Hellman key exchange using the same shared prime and generator as +specified above for ElGamal_, followed by symmetric AES encryption as described +above. This provides perfect forward secrecy [PFS]_ on the transport links. + +.. _tcp: + +NTCP connections +---------------- + +NTCP connections are negotiated with a 2048 Diffie-Hellman implementation, +using the router's identity to proceed with a station to station agreement, +followed by some encrypted protocol specific fields, with all subsequent data +encrypted with AES (as above). The primary reason to do the DH negotiation +instead of using ElGamalAES+SessionTag [ELG-AES]_ is that it provides +'(perfect) forward secrecy' [PFS]_, while ElGamalAES+SessionTag does not. + +In order to migrate to a more standardized implementation (TLS/SSL or even +SSH), the following issues must be addressed: + +1. Can we somehow reestablish sessions securely (ala session tags) or do we + need to do full negotiation each time? + +2. Can we simplify/avoid the x509 or other certificate formats and use our own + RouterInfo structure (which contains the ElGamal and DSA keys)? + +See the NTCP specification [NTCP]_ for details. + +.. _udp: + +UDP connections +--------------- + +SSU (the UDP transport) encrypts each packet with AES256/CBC with both an +explicit IV and MAC (HMAC-MD5-128) after agreeing upon an ephemeral session key +through a 2048 bit Diffie-Hellman exchange, station-to-station authentication +with the other router's DSA key, plus each network message has their own hash +for local integrity checking. + +See the SSU specification [SSU-KEYS]_ for details. + +WARNING - I2P's HMAC-MD5-128 used in SSU is apparently non-standard. +Apparently, an early version of SSU used HMAC-SHA256, and then it was switched +to MD5-128 for performance reasons, but left the 32-byte buffer size intact. +See HMACGenerator.java and the 2005-07-05 status notes [STATUS-HMAC]_ for +details. + + +References +========== + +.. [BENCHMARKS] + {{ site_url('misc/benchmarks', True) }} + + Crypto++ benchmarks, originally at http://www.eskimo.com/~weidai/benchmarks.html (now dead), + rescued from http://www.archive.org/, dated Apr 23, 2008. + +.. [CHOOSING-CONSTANTS] + http://article.gmane.org/gmane.comp.security.invisiblenet.iip.devel/343 + +.. [CryptixAESEngine] + https://github.com/i2p/i2p.i2p/tree/master/core/java/src/net/i2p/crypto/CryptixAESEngine.java + +.. [CryptixRijndael_Algorithm] + https://github.com/i2p/i2p.i2p/tree/master/core/java/src/net/i2p/crypto/CryptixRijndael_Algorithm.java + +.. [DSA] + http://en.wikipedia.org/wiki/Digital_Signature_Algorithm + +.. [DSAEngine] + https://github.com/i2p/i2p.i2p/tree/master/core/java/src/net/i2p/crypto/DSAEngine.java + +.. [ELG-AES] + {{ site_url('docs/how/elgamal-aes') }} + +.. [ElGamalEngine] + https://github.com/i2p/i2p.i2p/tree/master/core/java/src/net/i2p/crypto/ElGamalEngine.java + +.. [ElGamalAESEngine] + https://github.com/i2p/i2p.i2p/tree/master/core/java/src/net/i2p/crypto/ElGamalAESEngine.java + +.. [Koshiba2004] + Koshiba & Kurosawa. Short Exponent Diffie-Hellman Problems. PKC 2004, LNCS 2947, pp. 173-186 + + http://www.springerlink.com/content/2jry7cftp5bpdghm/ + + Full text: http://books.google.com/books?id=cXyiNZ2_Pa0C&lpg=PA173&ots=PNIz3dWe4g&pg=PA173#v=onepage&q&f=false + +.. [LeaseSet] + {{ ctags_url('LeaseSet') }} + +.. [MEETING-51] + {{ get_url('meetings_show', id=51) }} + +.. [MEETING-52] + {{ get_url('meetings_show', id=52) }} + +.. [NETDB-DELIVERY] + {{ site_url('docs/how/network-database', True) }}#delivery + +.. [NIST-800-57] + http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf + +.. [NTCP] + {{ site_url('docs/transport/ntcp', True) }} + +.. [PFS] + http://en.wikipedia.org/wiki/Perfect_forward_secrecy + +.. [PrivateKey] + {{ ctags_url('PrivateKey') }} + +.. [RFC-2313] + http://tools.ietf.org/html/rfc2313 + +.. [RFC-3526] + http://tools.ietf.org/html/rfc3526 + +.. [RFC-3526-S3] + http://tools.ietf.org/html/rfc3526#section-3 + +.. [SCI.CRYPT] + http://groups.google.com/group/sci.crypt/browse_thread/thread/1855a5efa7416677/339fa2f945cc9ba0#339fa2f945cc9ba0 + +.. [SHA-2] + https://en.wikipedia.org/wiki/SHA-2 + +.. [SHA256Generator] + https://github.com/i2p/i2p.i2p/tree/master/core/java/src/net/i2p/crypto/SHA256Generator.java + +.. [SigningPrivateKey] + {{ ctags_url('SigningPrivateKey') }} + +.. [SigningPublicKey] + {{ ctags_url('SigningPublicKey') }} + +.. [SSU-KEYS] + {{ site_url('docs/transport/ssu', True) }}#keys + +.. [STATUS-AES] + Feb. 7, 2006 Status Notes + + {{ get_url('blog_post', slug='2006/02/07/status') }} + +.. [STATUS-HMAC] + Jul. 5, 2005 Status Notes + + {{ get_url('blog_post', slug='2005/07/05/status') }} + +.. [TunnelBuild] + {{ ctags_url('TunnelBuild') }} + +.. [TUNNEL-TESTING] + {{ site_url('docs/how/tunnel-routing', True) }}#testing + +.. [UPDATES] + {{ spec_url('updates') }} + +.. [vanOorschot1996] + van Oorschot, Weiner. On Diffie-Hellman Key Agreement with Short Exponents. EuroCrypt '96 + + http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.14.5952&rep=rep1&type=pdf