Request Record Unencrypted

This is the specification of the tunnel BuildRequestRecord for ECIES-X25519 routers. Summary of changes:

• Remove unused 32-byte router hash
• Change request time from hours to minutes
• Add expiration field for future variable tunnel time
• Add more space for flags
• Add Mapping for additional build options
• AES-256 reply key and IV are not used for the hop's own reply record
• Unencrypted record is longer because there is less encryption overhead

The request record does not contain any ChaCha reply keys. Those keys are derived from a KDF. See below.

All fields are big-endian.

Unencrypted size: 464 bytes

bytes     0-3: tunnel ID to receive messages as, nonzero
bytes     4-7: next tunnel ID, nonzero
bytes    8-39: next router identity hash
bytes   40-71: AES-256 tunnel layer key
bytes  72-103: AES-256 tunnel IV key
bytes 104-135: AES-256 reply key
bytes 136-151: AES-256 reply IV
byte      152: flags
bytes 153-155: more flags, unused, set to 0 for compatibility
bytes 156-159: request time (in minutes since the epoch, rounded down)
bytes 160-163: request expiration (in seconds since creation)
bytes 164-167: next message ID
bytes   168-x: tunnel build options (Mapping)
bytes     x-x: other data as implied by flags or options
bytes   x-463: random padding

The flags field is the same as defined in [Tunnel-Creation] and contains the following:

Bit order: 76543210 (bit 7 is MSB)
bit 7: if set, allow messages from anyone
bit 6: if set, allow messages to anyone, and send the reply to the
       specified next hop in a Tunnel Build Reply Message
bits 5-0: Undefined, must set to 0 for compatibility with future options

Bit 7 indicates that the hop will be an inbound gateway (IBGW). Bit 6 indicates that the hop will be an outbound endpoint (OBEP). If neither bit is set, the hop will be an intermediate participant. Both cannot be set at once.

The request exipration is for future variable tunnel duration. For now, the only supported value is 600 (10 minutes).

The tunnel build options is a Mapping structure as defined in [Common]. This is for future use. No options are currently defined. If the Mapping structure is empty, this is two bytes 0x00 0x00. The maximum size of the Mapping (including the length field) is 296 bytes, and the maximum value of the Mapping length field is 294.

Request Record Encrypted

All fields are big-endian except for the ephemeral public key which is little-endian.

Encrypted size: 528 bytes

bytes    0-15: Hop's truncated identity hash
bytes   16-47: Sender's ephemeral X25519 public key
bytes  48-511: ChaCha20 encrypted BuildRequestRecord
bytes 512-527: Poly1305 MAC

Reply Record Unencrypted

This is the specification of the tunnel BuildReplyRecord for ECIES-X25519 routers. Summary of changes:

• Add Mapping for build reply options
• Unencrypted record is longer because there is less encryption overhead

ECIES replies are encrypted with ChaCha20/Poly1305.

All fields are big-endian.

Unencrypted size: 512 bytes

bytes    0-x: Tunnel Build Reply Options (Mapping)
bytes    x-x: other data as implied by options
bytes  x-510: Random padding
byte     511: Reply byte

The tunnel build reply options is a Mapping structure as defined in [Common]. This is for future use. No options are currently defined. If the Mapping structure is empty, this is two bytes 0x00 0x00. The maximum size of the Mapping (including the length field) is 511 bytes, and the maximum value of the Mapping length field is 509.

The reply byte is one of the following values as defined in [Tunnel-Creation] to avoid fingerprinting:

• 0x00 (accept)
• 30 (TUNNEL_REJECT_BANDWIDTH)

Reply Record Encrypted

Encrypted size: 528 bytes

bytes   0-511: ChaCha20 encrypted BuildReplyRecord
bytes 512-527: Poly1305 MAC

After full transition to ECIES records, ranged padding rules are the same as for request records.

KDF for Initial ck and h

This is standard [NOISE] for pattern "N" with a standard protocol name.

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.

KDF for Request Record

ElGamal tunnel creators generate an ephemeral X25519 keypair for each ECIES hop in the tunnel, and use scheme above for encrypting their BuildRequestRecord. ElGamal tunnel creators will use the scheme prior to this spec for encrypting to ElGamal hops.

ECIES tunnel creators will need to encrypt to each of the ElGamal hop's public key using the scheme defined in [Tunnel-Creation]. ECIES tunnel creators will use the above scheme for encrypting to ECIES hops.

This means that tunnel hops will only see encrypted records from their same encryption type.

For ElGamal and ECIES tunnel creators, they will generate unique ephemeral X25519 keypairs per-hop for encrypting to ECIES hops.

IMPORTANT: Ephemeral keys must be unique per ECIES hop, and per build record. Failing to use unique keys opens an attack vector for colluding hops to confirm they are in the same tunnel.

// Each hop'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 build requests

// Sender generates an X25519 ephemeral keypair per ECIES hop in the VTBM (sesk, sepk)
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 Hop's static public key.
// Each Hop, finds the record w/ their truncated identity hash,
// and 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)
// Save for Reply Record KDF
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)
// Save for Reply Record KDF
h = SHA256(h || ciphertext)

replyKey, layerKey and layerIV must still be included inside ElGamal records, and can be generated randomly.

Notes

Garlic wrapping of the messages hides them from the OBEP (for an inbound build) or the IBGW (for an outbound build). This is recommended but not required. If the OBEP and IBGW are the same router, it is not necessary.

Short Request Record Unencrypted

Summary of changes from long records:

• Change unencrypted length from 464 to 154 bytes
• Change encrypted length from 528 to 218 bytes
• Remove layer and reply keys and IVs, they will be generated from a KDF

The request record does not contain any ChaCha reply keys. Those keys are derived from a KDF. See below.

All fields are big-endian.

Unencrypted size: 154 bytes.

bytes     0-3: tunnel ID to receive messages as, nonzero
bytes     4-7: next tunnel ID, nonzero
bytes    8-39: next router identity hash
byte       40: flags
bytes   41-42: more flags, unused, set to 0 for compatibility
byte       43: layer encryption type
bytes   44-47: request time (in minutes since the epoch, rounded down)
bytes   48-51: request expiration (in seconds since creation)
bytes   52-55: next message ID
bytes    56-x: tunnel build options (Mapping)
bytes     x-x: other data as implied by flags or options
bytes   x-153: random padding (see below)

The flags field is the same as defined in [Tunnel-Creation] and contains the following:

Bit order: 76543210 (bit 7 is MSB)
bit 7: if set, allow messages from anyone
bit 6: if set, allow messages to anyone, and send the reply to the
       specified next hop in a Tunnel Build Reply Message
bits 5-0: Undefined, must set to 0 for compatibility with future options

Bit 7 indicates that the hop will be an inbound gateway (IBGW). Bit 6 indicates that the hop will be an outbound endpoint (OBEP). If neither bit is set, the hop will be an intermediate participant. Both cannot be set at once.

Layer encryption type: 0 for AES (as in current tunnels); 1 for future (ChaCha?)

The request exipration is for future variable tunnel duration. For now, the only supported value is 600 (10 minutes).

The creator ephemeral public key is an ECIES key, big-endian. It is used for the KDF for the IBGW layer and reply keys and IVs. This is only included in the plaintext record in an Inbound Tunnel Build message. It is required because there is no DH at this layer for the build record.

The tunnel build options is a Mapping structure as defined in [Common]. This is for future use. No options are currently defined. If the Mapping structure is empty, this is two bytes 0x00 0x00. The maximum size of the Mapping (including the length field) is 98 bytes, and the maximum value of the Mapping length field is 96.

Short Request Record Encrypted

All fields are big-endian except for the ephemeral public key which is little-endian.

Encrypted size: 218 bytes

bytes    0-15: Hop's truncated identity hash
bytes   16-47: Sender's ephemeral X25519 public key
bytes  48-201: ChaCha20 encrypted ShortBuildRequestRecord
bytes 202-217: Poly1305 MAC

Short Reply Record Unencrypted

Summary of changes from long records:

• Change unencrypted length from 512 to 202 bytes
• Change encrypted length from 528 to 218 bytes

ECIES replies are encrypted with ChaCha20/Poly1305.

All fields are big-endian.

Unencrypted size: 202 bytes.

bytes    0-x: Tunnel Build Reply Options (Mapping)
bytes    x-x: other data as implied by options
bytes  x-200: Random padding (see below)
byte     201: Reply byte

The tunnel build reply options is a Mapping structure as defined in [Common]. This is for future use. No options are currently defined. If the Mapping structure is empty, this is two bytes 0x00 0x00. The maximum size of the Mapping (including the length field) is 201 bytes, and the maximum value of the Mapping length field is 199.

The reply byte is one of the following values as defined in [Tunnel-Creation] to avoid fingerprinting:

• 0x00 (accept)
• 30 (TUNNEL_REJECT_BANDWIDTH)

An additional reply value may be defined in the future to represent rejection for unsupported options.

Short Reply Record Encrypted

Encrypted size: 218 bytes

bytes   0-201: ChaCha20 encrypted ShortBuildReplyRecord
bytes 202-217: Poly1305 MAC

Record Encryption

The hop's own reply record is encrypted with ChaCha20/Poly1305. This is the same as for the long record specification above, EXCEPT that 'n' is the record number 0-7, instead of always being 0. See [RFC-7539].

// AEAD parameters
k = replyKey from KDF above
n = record number 0-7
plaintext = 202 byte build reply record
ad = h from build request

ciphertext = ENCRYPT(k, n, plaintext, ad)

The other records are iteratively and symmetrically encrypted at each hop with ChaCha20 (NOT ChaCha20/Poly1305). This is different from the long record specification above, which uses AES and does not use the record number.

The record number is put in the IV at byte 4, because ChaCha20 uses a 12-byte IV with a little-endian nonce at bytes 4-11. See [RFC-7539].

// Parameters
k = replyKey from KDF above
n = record number 0-7
iv = 12 bytes, all zeros except iv[4] = n
plaintext = 218 byte encrypted record

ciphertext = ENCRYPT(k, iv, plaintext)

Garlic Encryption

Garlic wrapping of the messages hides them from the OBEP (for an inbound build) or the IBGW (for an outbound build). This is recommended but not required. If the OBEP and IBGW are the same router, it is not necessary.

Garlic encryption of an inbound Short Tunnel Build Message, by the creator, encrypted to the ECIES IBGW, uses Noise 'N' encryption, as defined in [ECIES-ROUTERS].

Garlic encryption of an Outbound Tunnel Build Reply Message, by the OBEP, encrypted to the creator, uses They are encrypted as Existing Session messages with the 32-byte garlic reply key and 8-byte garlic reply tag from the KDF above. The format is as specified for replies to Database Lookups in [I2NP], [ECIES-ROUTERS], and [ECIES-X25519].

Layer Encryption

This specification includes a layer encryption type field in the build request record. The only layer encryption currently supported is type 0, which is AES. This is unchanged from previous specifications, except that the layer key and IV key are derived from the KDF above rather than being included in the build request record.

Adding new layer encryption types, for example ChaCha20, is a topic for additional research, and is not currently a part of this specification.