Cryptographic Primitives

The primitives required to implement this specification are:

• AES-256-CBC as in [Cryptography]
• STREAM ChaCha20/Poly1305 functions: ENCRYPT(k, n, plaintext, ad) and DECRYPT(k, n, ciphertext, ad) - as in [NTCP2] [ECIES-X25519] and [RFC-7539]
• X25519 DH functions - as in [NTCP2] and [ECIES-X25519]
• HKDF(salt, ikm, info, n) - as in [NTCP2] and [ECIES-X25519]

Other Noise functions defined elsewhere:

• MixHash(d) - as in [NTCP2] and [ECIES-X25519]
• MixKey(d) - as in [NTCP2] and [ECIES-X25519]

Noise Protocol Framework

This specification provides the requirements based on the Noise Protocol Framework [NOISE] (Revision 34, 2018-07-11). In Noise parlance, Alice is the initiator, and Bob is the responder.

It is based on the Noise protocol Noise_N_25519_ChaChaPoly_SHA256. This Noise protocol uses the following primitives:

• One-Way Handshake Pattern: N Alice does not transmit her static key to Bob (N)
• DH Function: X25519 X25519 DH with a key length of 32 bytes as specified in [RFC-7748].
• Cipher Function: ChaChaPoly AEAD_CHACHA20_POLY1305 as specified in [RFC-7539] section 2.8. 12 byte nonce, with the first 4 bytes set to zero. Identical to that in [NTCP2].
• Hash Function: SHA256 Standard 32-byte hash, already used extensively in I2P.

Handshake Patterns

Handshakes use [Noise] handshake patterns.

The following letter mapping is used:

• e = one-time ephemeral key
• s = static key
• p = message payload

The build request is identical to the Noise N pattern. This is also identical to the first (Session Request) message in the XK pattern used in [NTCP2].

<- s
...
e es p ->

Message encryption

Messages are created and asymmetrically encrypted to the target router. This asymmetric encryption of messages is currently ElGamal as defined in [Cryptography] and contains a SHA-256 checksum. This design is not forward-secret.

The ECIES design uses the one-way Noise pattern "N" with ECIES-X25519 ephemeral-static DH, with an HKDF, and ChaCha20/Poly1305 AEAD for forward secrecy, integrity, and authentication. Alice is the anonymous message sender, a router or destination. The target ECIES router is Bob.

Reply encryption

Replies are not part of this protocol, as Alice is anonymous. The reply keys, if any, are bundled in the request message. See the I2NP specification [I2NP] for Database Lookup Messages.

Replies to Database Lookup messages are Database Store or Database Search Reply messages. They are encrypted as Existing Session messages with the 32-byte reply key and 8-byte reply tag as specified in [I2NP] and [Prop154].

There are no explicit replies to Database Store messages. The sender may bundle its own reply as a Garlic Message to itself, containing a Delivery Status message.

Request Encryption

The request encryption is the same as that specified in [Tunnel-Creation-ECIES] and [Prop152], using the Noise "N" pattern.

Replies to lookups will be encrypted with a ratchet tag if requested in the lookup. Database Lookup request messages contain the 32-byte reply key and 8-byte reply tag as specified in [I2NP] and [Prop154]. The key and tag are used to encrypt the reply.

Tag sets are not created. The zero static key scheme specified in ECIES-X25519-AEAD-Ratchet [Prop144] and [ECIES] will not be used. Ephemeral keys will not be Elligator2-encoded.

Generally, these will be New Session messages and will be sent with a zero static key (no binding or session), as the sender of the message is anonymous.

This is the "e" message pattern:

// Define protocol_name.
Set protocol_name = "Noise_N_25519_ChaChaPoly_SHA256"
(31 bytes, US-ASCII encoded, no NULL termination).

// Define Hash h = 32 bytes
// Pad to 32 bytes. Do NOT hash it, because it is not more than 32 bytes.
h = protocol_name || 0

Define ck = 32 byte chaining key. Copy the h data to ck.
Set chainKey = h

// MixHash(null prologue)
h = SHA256(h);

// up until here, can all be precalculated by all routers.

// Target router's X25519 static keypair (hesk, hepk) from the Router Identity
hesk = GENERATE_PRIVATE()
hepk = DERIVE_PUBLIC(hesk)

// MixHash(hepk)
// || below means append
h = SHA256(h || hepk);

// up until here, can all be precalculated by each router
// for all incoming messages

// Sender generates an X25519 ephemeral keypair
sesk = GENERATE_PRIVATE()
sepk = DERIVE_PUBLIC(sesk)

// MixHash(sepk)
h = SHA256(h || sepk);

End of "e" message pattern.

This is the "es" message pattern:

// Noise es
// Sender performs an X25519 DH with receiver's static public key.
// The target router
// extracts the sender's ephemeral key preceding the encrypted record.
sharedSecret = DH(sesk, hepk) = DH(hesk, sepk)

// MixKey(DH())
//[chainKey, k] = MixKey(sharedSecret)
// ChaChaPoly parameters to encrypt/decrypt
keydata = HKDF(chainKey, sharedSecret, "", 64)
// Chain key is not used
//chainKey = keydata[0:31]

// AEAD parameters
k = keydata[32:64]
n = 0
plaintext = 464 byte build request record
ad = h
ciphertext = ENCRYPT(k, n, plaintext, ad)

End of "es" message pattern.

// MixHash(ciphertext) is not required
//h = SHA256(h || ciphertext)