Notes

• Lookup types are currently bits 3-2 in the Database Lookup Message. Any additional types would require use of bit 4.
• All store types are odd since upper bits in the Database Store Message type field are ignored by old routers. We would rather have the parse fail as an LS than as a compressed RI.
• Should type be explicit or implicit or neither in the data covered by the signature?

Justification

• Unpublished/published: For use when sending a database store end-to-end, the sending router may wish to indicate that this leaseset should not be sent to others. We currently use heuristics to maintain this state.
• Published: Replaces the complex logic required to determine the 'version' of the leaseset. Currently, the version is the expiration of the last-expiring lease, and a publishing router must increment that expiration by at least 1ms when publishing a leaseset that only removes an older lease.
• Expires: Allows for an expiration of a netdb entry to be earlier than that of its last-expiring leaseset. May not be useful for LS2, where leasesets are expected to remain with a 11-minute maximum expiration, but for other new types, it is necessary (see Meta LS and Service Record below).
• Offline keys are optional, to reduce initial/required implementation complexity.

Notes

• Routers should not publish a LS more than once a second. If they do, they must artificially increment the published timestamp by 1 over the previously published LS.
• Router implementations could cache the transient keys and signature to avoid verification every time. In particular, floodfills, and routers at both ends of long-lived connections, could benefit from this.
• Offline keys and signature are only appropriate for long-lived destinations, i.e. servers, not clients.

Format

Standard LS2 Header as specified above

Standard LS2 Type-Specific Part
- Properties (Mapping as specified in common structures spec, 2 zero bytes if none)
- Number of key sections to follow (1 byte, max TBD)
- Key sections:
  - Encryption type (2 bytes, big endian)
  - Encryption key length (2 bytes, big endian)
    This is explicit, so floodfills can parse LS2 with unknown encryption types.
  - Encryption key (number of bytes specified)
- Number of lease2s (1 byte)
- Lease2s (40 bytes each)
  These are leases, but with a 4-byte instead of an 8-byte expiration,
  seconds since the epoch (rolls over in 2106)

Standard LS2 Signature:
- Signature
  If flag indicates offline keys, this is signed by the transient pubkey,
  otherwise, by the destination pubkey
  Length as implied by sig type of signing key
  The signature is of everything above.

Justification

• Properties: Future expansion and flexibility. Placed first in case necessary for parsing of the remaining data.
• Multiple encryption type/public key pairs are to ease transition to new encryption types. The other way to do it is to publish multiple leasesets, possibly using the same tunnels, as we do now for DSA and EdDSA destinations. Identification of the incoming encryption type on a tunnel may be done with the existing session tag mechanism, and/or trial decryption using each key. Lengths of the incoming messages may also provide a clue.

Discussion

This proposal continues to use the public key in the leaseset for the end-to-end encryption key, and leaves the public key field in the Destination unused, as it is now. The encryption type is not specified in the Destination key certificate, it will remain 0.

A rejected alternative is to specify the encryption type in the Destination key certificate, use the public key in the Destination, and not use the public key in the leaseset. We do not plan to do this.

Benefits of LS2:

• Location of actual public key doesn't change.
• Encryption type, or public key, may change without changing the Destination.
• Removes unused revocation field
• Basic compatibility with other DatabaseEntry types in this proposal
• Allow multiple encryption types

Drawbacks of LS2:

• Location of public key and encryption type differs from RouterInfo
• Maintains unused public key in leaseset
• Requires implementation across the network; in the alternative, experimental encryption types may be used, if allowed by floodfills (but see related proposals 136 and 137 about support for experimental sig types). The alternative proposal could be easier to implement and test for experimental encryption types.

New Encryption Issues

Some of this is out-of-scope for this proposal, but putting notes here for now as we don't have a separate encryption proposal yet. See also the ECIES proposals 144 and 145.

• The encryption type represents the combination of curve, key length, and end-to-end scheme, including KDF and MAC, if any.
• We have included a key length field, so that the LS2 is parsable and verifiable by the floodfill even for unknown encryption types.
• The first new encryption type to be proposed will probably be ECIES/X25519. How it's used end-to-end (either a slightly modified version of ElGamal/AES+SessionTag or something completely new, e.g. ChaCha/Poly) will be specified in one or more separate proposals. See also the ECIES proposals 144 and 145.

Notes

• 8-byte expiration in leases changed to 4 bytes.
• If we ever implement revocation, we can do it with an expires field of zero, or zero leases, or both. No need for a separate revocation key.
• Encryption keys are in order of server preference, most-preferred first. Default client behavior is to select the first key with a supported encryption type. Clients may use other selection algorithms based on encryption support, relative performance, and other factors.

Definitions

We define the following functions corresponding to the cryptographic building blocks used for encrypted LS2:

CSRNG(n)

n-byte output from a cryptographically-secure random number generator.

In addition to the requirement of CSRNG being cryptographically-secure (and thus suitable for generating key material), it MUST be safe for some n-byte output to be used for key material when the byte sequences immediately preceding and following it are exposed on the network (such as in a salt, or encrypted padding). Implementations that rely on a potentially-untrustworthy source should hash any output that is to be exposed on the network [PRNG-REFS].

H(p, d)

SHA-256 hash function that takes a personalization string p and data d, and produces an output of length 32 bytes.

Use SHA-256 as follows:

H(p, d) := SHA-256(p || d)

STREAM

The ChaCha20 stream cipher as specified in [RFC-7539-S2.4], with the initial counter set to 1. S_KEY_LEN = 32 and S_IV_LEN = 12.

ENCRYPT(k, iv, plaintext)

Encrypts plaintext using the cipher key k, and nonce iv which MUST be unique for the key k. Returns a ciphertext that is the same size as the plaintext.

The entire ciphertext must be indistinguishable from random if the key is secret.

DECRYPT(k, iv, ciphertext)

Decrypts ciphertext using the cipher key k, and nonce iv. Returns the plaintext.

SIG

The RedDSA signature scheme (corresponding to SigType 11) with key blinding. It has the following functions:

DERIVE_PUBLIC(privkey)

Returns the public key corresponding to the given private key.

SIGN(privkey, m)

Returns a signature by the private key privkey over the given message m.

VERIFY(pubkey, m, sig)

Verifies the signature sig against the public key pubkey and message m. Returns true if the signature is valid, false otherwise.

It must also support the following key blinding operations:

GENERATE_ALPHA(data, secret)

Generate alpha for those who know the data and an optional secret. The result must be identically distributed as the private keys.

BLIND_PRIVKEY(privkey, alpha)

Blinds a private key, using a secret alpha.

BLIND_PUBKEY(pubkey, alpha)

Blinds a public key, using a secret alpha. For a given keypair (privkey, pubkey) the following relationship holds:

BLIND_PUBKEY(pubkey, alpha) ==
DERIVE_PUBLIC(BLIND_PRIVKEY(privkey, alpha))

DH

X25519 public key agreement system. Private keys of 32 bytes, public keys of 32 bytes, produces outputs of 32 bytes. It has the following functions:

GENERATE_PRIVATE()

Generates a new private key.

DERIVE_PUBLIC(privkey)

Returns the public key corresponding to the given private key.

DH(privkey, pubkey)

Generates a shared secret from the given private and public keys.

HKDF(salt, ikm, info, n)

A cryptographic key derivation function which takes some input key material ikm (which should have good entropy but is not required to be a uniformly random string), a salt of length 32 bytes, and a context-specific 'info' value, and produces an output of n bytes suitable for use as key material.

Use HKDF as specified in [RFC-5869], using the HMAC hash function SHA-256 as specified in [RFC-2104]. This means that SALT_LEN is 32 bytes max.

Format

The encrypted LS2 format consists of three nested layers:

• An outer layer containing the necessary plaintext information for storage and retrieval.
• A middle layer that handles client authentication.
• An inner layer that contains the actual LS2 data.

The overall format looks like:

Layer 0 data + Enc(layer 1 data + Enc(layer 2 data)) + Signature

Note that encrypted LS2 is blinded. The Destination is not in the header. DHT storage location is SHA-256(sig type || blinded public key), and rotated daily.

Does NOT use the standard LS2 header specified above.

Blinding Key Derivation

We use the following scheme for key blinding, based on Ed25519 and ZCash RedDSA [ZCASH]. The Re25519 signatures are over the Ed25519 curve, using SHA-512 for the hash.

We do not use Tor's rend-spec-v3.txt appendix A.2 [TOR-REND-SPEC-V3], which has similar design goals, because its blinded public keys may be off the prime-order subgroup, with unknown security implications.

// GENERATE_ALPHA(destination, date, secret)

// secret is optional, else zero-length
A = destination's signing public key
stA = signature type of A, 2 bytes big endian (0x0007 or 0x000b)
stA' = signature type of blinded public key A', 2 bytes big endian (0x000b)
keydata = A || stA || stA'
datestring = 8 bytes ASCII YYYYMMDD from the current date UTC
secret = UTF-8 encoded string
seed = HKDF(H("I2PGenerateAlpha", keydata), datestring || secret, "i2pblinding1", 64)
// treat seed as a 64 byte little-endian value
alpha = seed mod L

// BLIND_PRIVKEY()

alpha = GENERATE_ALPHA(destination, date, secret)
// If for a Ed25519 private key (type 7)
seed = destination's signing private key
a = left half of SHA512(seed) and clamped as usual for Ed25519
// else, for a Red25519 private key (type 11)
a = destination's signing private key
// Addition using scalar arithmentic
blinded signing private key = a' = BLIND_PRIVKEY(a, alpha) = (a + alpha) mod L
blinded signing public key = A' = DERIVE_PUBLIC(a')

// BLIND_PUBKEY()

alpha = GENERATE_ALPHA(destination, date, secret)
A = destination's signing public key
// Addition using group elements (points on the curve)
blinded public key = A' = BLIND_PUBKEY(A, alpha) = A + DERIVE_PUBLIC(alpha)

T = 80 random bytes
r = H*(T || publickey || message)
// rest is the same as in Ed25519

// same as in Ed25519

Encryption and processing

A = destination's signing public key
stA = signature type of A, 2 bytes big endian (0x0007 or 0x000b)
stA' = signature type of A', 2 bytes big endian (0x000b)
keydata = A || stA || stA'
credential = H("credential", keydata)

subcredential = H("subcredential", credential || blindedPublicKey)

outerInput = subcredential || publishedTimestamp

outerSalt = CSRNG(32)

keys = HKDF(outerSalt, outerInput, "ELS2_L1K", 44)
outerKey = keys[0:31]
outerIV = keys[32:43]

outerCiphertext = outerSalt || ENCRYPT(outerKey, outerIV, outerPlaintext)

outerSalt = outerCiphertext[0:31]

outerInput = subcredential || publishedTimestamp
keys = HKDF(outerSalt, outerInput, "ELS2_L1K", 44)
outerKey = keys[0:31]
outerIV = keys[32:43]

outerPlaintext = DECRYPT(outerKey, outerIV, outerCiphertext[32:end])

innerInput = authCookie || subcredential || publishedTimestamp
innerSalt = CSRNG(32)
keys = HKDF(innerSalt, innerInput, "ELS2_L2K", 44)
innerKey = keys[0:31]
innerIV = keys[32:43]
innerCiphertext = innerSalt || ENCRYPT(innerKey, innerIV, innerPlaintext)

innerInput = authCookie || subcredential || publishedTimestamp
innerSalt = innerCiphertext[0:31]
keys = HKDF(innerSalt, innerInput, "ELS2_L2K", 44)
innerKey = keys[0:31]
innerIV = keys[32:43]
innerPlaintext = DECRYPT(innerKey, innerIV, innerCiphertext[32:end])

Per-client authorization

When client authorization is enabled for a Destination, the server maintains a list of clients they are authorizing to decrypt the encrypted LS2 data. The data stored per-client depends on the authorization mechanism, and includes some form of key material that each client generates and sends to the server via a secure out-of-band mechanism.

There are two alternatives for implementing per-client authorization:

authCookie = CSRNG(32)
esk = GENERATE_PRIVATE()
epk = DERIVE_PUBLIC(esk)

sharedSecret = DH(esk, cpk_i)
authInput = sharedSecret || cpk_i || subcredential || publishedTimestamp
okm = HKDF(epk, authInput, "ELS2_XCA", 52)
clientKey_i = okm[0:31]
clientIV_i = okm[32:43]
clientID_i = okm[44:51]
clientCookie_i = ENCRYPT(clientKey_i, clientIV_i, authCookie)

sharedSecret = DH(csk_i, epk)
authInput = sharedSecret || cpk_i || subcredential || publishedTimestamp
okm = HKDF(epk, authInput, "ELS2_XCA", 52)
clientKey_i = okm[0:31]
clientIV_i = okm[32:43]
clientID_i = okm[44:51]

authCookie = DECRYPT(clientKey_i, clientIV_i, clientCookie_i)

authCookie = CSRNG(32)
authSalt = CSRNG(32)

authInput = psk_i || subcredential || publishedTimestamp
okm = HKDF(authSalt, authInput, "ELS2PSKA", 52)
clientKey_i = okm[0:31]
clientIV_i = okm[32:43]
clientID_i = okm[44:51]
clientCookie_i = ENCRYPT(clientKey_i, clientIV_i, authCookie)

authInput = psk_i || subcredential || publishedTimestamp
okm = HKDF(authSalt, authInput, "ELS2PSKA", 52)
clientKey_i = okm[0:31]
clientIV_i = okm[32:43]
clientID_i = okm[44:51]

authCookie = DECRYPT(clientKey_i, clientIV_i, clientCookie_i)

Encrypted LS with Base 32 Addresses

See proposal 149.

You can't use an encrypted LS2 for bittorrent, because of compact announce replies which are 32 bytes. The 32 bytes contain only the hash. There is no room for an indication that the leaseset is encrypted, or the signature types.

Encrypted LS with Offline Keys

For encrypted leasesets with offline keys, the blinded private keys must also be generated offline, one for each day.

As the optional offline signature block is in the cleartext part of the encryted leaseset, anybody scraping the floodfills could use this to track the leaseset (but not decrypt it) over several days. To prevent this, the owner of the keys should generate new transient keys for each day as well. Both the transient and blinded keys can be generated in advance, and delivered to the router in a batch.

There is no file format defined in this proposal for packaging multiple transient and blinded keys and providing them to the client or router. There is no I2CP protocol enhancement defined in this proposal to support encrypted leasesets with offline keys.

Notes

• A service using encrypted leasesets would publish the encrypted version to the floodfills. However, for efficiency, it would send unencrypted leasesets to clients in the wrapped garlic message, once authenticated (via whitelist, for example).
• Floodfills may limit the max size to a reasonable value to prevent abuse.
• After decryption, several checks should be made, including that the inner timestamp and expiration match those at the top level.
• ChaCha20 was selected over AES. While the speeds are similar if AES hardware support is available, ChaCha20 is 2.5-3x faster when AES hardware support is not available, such as on lower-end ARM devices.
• We do not care enough about speed to use keyed BLAKE2b. It has an output size large enough to accommodate the largest n we require (or we can call it once per desired key with a counter argument). BLAKE2b is much faster than SHA-256, and keyed-BLAKE2b would reduce the total number of hash function calls. However, see proposal 148, where it is proposed that we switch to BLAKE2b for other reasons. [UNSCIENTIFIC-KDF-SPEEDS]

Format

Standard LS2 Header as specified above

Meta LS2 Type-Specific Part
- Properties (Mapping as specified in common structures spec, 2 zero bytes if none)
- Number of entries (1 byte) Maximum TBD
- Entries. Each entry contains: (40 bytes)
  - Hash (32 bytes)
  - Flags (2 bytes)
    TBD. Set all to zero for compatibility with future uses.
  - Type (1 byte) The type of LS it is referencing;
    1 for LS, 3 for LS2, 5 for encrypted, 7 for meta, 0 for unknown.
  - Cost (priority) (1 byte)
  - Expires (4 bytes) (4 bytes, big endian, seconds since epoch, rolls over in 2106)
- Number of revocations (1 byte) Maximum TBD
- Revocations: Each revocation contains: (32 bytes)
  - Hash (32 bytes)

Standard LS2 Signature:
- Signature (40+ bytes)
  The signature is of everything above.

Flags and properties: for future use

Notes

• A distributed service using this would have one or more "masters" with the private key of the service destination. They would (out of band) determine the current list of active destinations and would publish the Meta LS2. For redundancy, multiple masters could multihome (i.e. concurrently publish) the Meta LS2.
• A distributed service could start with a single destination or use old-style multihoming, then transition to a Meta LS2. A standard LS lookup could return any one of a LS, LS2, or Meta LS2.
• When a service uses a Meta LS2, it has no tunnels (leases).

Format

Standard LS2 Header as specified above

Service Record Type-Specific Part
- Port (2 bytes, big endian) (0 if unspecified)
- Hash of service name (32 bytes)

Standard LS2 Signature:
- Signature (40+ bytes)
  The signature is of everything above.

Notes

• If expires is all zeros, the floodfill should revoke the record and no longer include it in the service list.
• Storage: The floodfill may strictly throttle storage of these records and limit the number of records stored per hash and their expiration. A whilelist of hashes may also be used.
• Any other netdb type at the same hash has priority, so a service record can never overwrite a LS/RI, but a LS/RI will overwrite all service records at that hash.

Format

Does NOT use the standard LS2 header specified above.

- Type (1 byte)
  Not actually in header, but part of data covered by signature.
  Take from field in Database Store Message.
- Hash of the service name (implicit, in the Database Store message)
- Hash of the Creator (floodfill) (32 bytes)
- Published timestamp (8 bytes, big endian)

- Number of Short Service Records (1 byte)
- List of Short Service Records:
  Each Short Service Record contains (90+ bytes)
  - Dest hash (32 bytes)
  - Published timestamp (8 bytes, big endian)
  - Expires (4 bytes, big endian) (offset from published in ms)
  - Flags (2 bytes)
  - Port (2 bytes, big endian)
  - Sig length (2 bytes, big endian)
  - Signature of dest (40+ bytes)

- Number of Revocation Records (1 byte)
- List of Revocation Records:
  Each Revocation Record contains (86+ bytes)
  - Dest hash (32 bytes)
  - Published timestamp (8 bytes, big endian)
  - Flags (2 bytes)
  - Port (2 bytes, big endian)
  - Sig length (2 bytes, big endian)
  - Signature of dest (40+ bytes)

- Signature of floodfill (40+ bytes)
  The signature is of everything above.

To verify signature of the Service List:

• prepend the hash of the service name
• remove the hash of the creator
• Check signature of the modified contents

To verify signature of each Short Service Record:

• Fetch destination
• Check signature of (published timestamp + expires + flags + port + Hash of service name)

To verify signature of each Revocation Record:

• Fetch destination
• Check signature of (published timestamp + 4 zero bytes + flags + port + Hash of service name)

Notes

• We use signature length instead of sig type so we can support unknown signature types.
• There is no expiration of a service list, recipients may make their own decision based on policy or the expiration of the individual records.
• Service Lists are not flooded, only individual Service Records are. Each floodfill creates, signs, and caches a Service List. The floodfill uses its own policy for cache time and the maximum number of service and revocation records.

Changes

Flags byte: Lookup type field, currently bits 3-2, expands to bits 4-2.
Lookup type 0x04 is defined as the service list lookup.

Add note: Service list loookup may only be sent to floodfills with a minimum version.
Minimum version is 0.9.38.

Changes

Type byte: Type field, currently bit 0, expands to bits 3-0.
Type 3 is defined as a LS2 store.
Type 5 is defined as a encrypted LS2 store.
Type 7 is defined as a meta LS2 store.
Type 9 is defined as a service record store.
Type 11 is defined as a service list store.
Other types are undefined and invalid.

Add note: All new types may only be published to floodfills with a minimum version.
Minimum version is 0.9.38.

Justification

• For the router to parse the store type, the type must be in the message, unless it is passed to the router before hand in the session config. For for common parsing code, it's easier to have it in the message itself.
• For the router to know the type and length of the private key, it must be after the lease set, unless the parser knows the type before hand in the session config. For for common parsing code, it's easier to know it from the message itself.
• The signing private key, previously defined for revocation and unused, is not present in LS2.

Message Type

The message type for the Create Leaseset2 Message is 41.

Format

Session ID
Type byte: Type of lease set to follow
           Type 1 is a LS
           Type 3 is a LS2
           Type 5 is a encrypted LS2
           Type 7 is a meta LS2
LeaseSet: type specified above
Number of private keys to follow (1 byte)
Encryption Private Keys: For each public key in the lease set,
                         in the same order
                         (Not present for Meta LS2)
                         - Encryption type (2 bytes, big endian)
                         - Encryption key length (2 bytes, big endian)
                         - Encryption key (number of bytes specified)

Notes

• Minimum router version is 0.9.39.
• Preliminary version with message type 40 was in 0.9.38 but the format was changed. Type 40 is abandoned and is unsupported.

Issues

• More changes are needed to support encrypted and meta LS.

Justification

• The router needs to know if a destination is blinded. If it is blinded and uses a secret or per-client authentication, it needs to have that information as well.
• A Host Lookup of a new-format b32 address ("b33") tells the router that the address is blinded, but there's no mechanism to pass the secret or private key to the router in the Host Lookup message. While we could extend the Host Lookup message to add that information, it's cleaner to define a new message.
• We need a programmatic way for the client to tell the router. Otherwise, the user would have to manually configure each destination.

Usage

Before a client sends a message to a blinded destination, it must either lookup the "b33" in a Host Lookup message, or send a Blinding Info message. If the blinded destination requires a secret or per-client authentication, the client must send a Blinding Info message.

The router does not send a reply to this message.

Message Type

The message type for the Blinding Info Message is 42.

Format

Session ID
Flags:       1 byte
             Bit order: 76543210
             Bit 0: 0 for everybody, 1 for per-client
             Bits 3-1: Authentication scheme, if bit 0 is set to 1 for per-client, otherwise 000
                       000: DH client authentication (or no per-client authentication)
                       001: PSK client authentication
             Bit 4: 1 if secret required, 0 if no secret required
             Bits 7-5: Unused, set to 0 for future compatibility
Type byte:   Endpoint type to follow
             Type 0 is a Hash
             Type 1 is a host name String
             Type 2 is a Destination
             Type 3 is a Sig Type and Signing Public Key
Blind Type:  2 byte blinded sig type (big endian)
Expiration:  4 bytes, big endian, seconds since epoch
Endpoint:    Data as specified above
             For type 0: 32 byte binary hash
             For type 1: host name String
             For type 2: binary Destination
             For type 3: 2 byte sig type (big endian)
                         Signing Public Key (length as implied by sig type)
Private Key: Only if flag bit 0 is set to 1
             A 32-byte ECIES_X25519 private key
Secret:      Only if flag bit 4 is set to 1
             A secret String

Notes

• Minimum router version is 0.9.43

Issues

Justification

A client doesn't know a priori that a given Hash will resolve to a Meta LS.

If a leaseset lookup for a Destination returns a Meta LS, the router will do the recursive resolution. For datagrams, the client side does not need to know; however, for streaming, where the protocol checks the destination in the SYN ACK, it must know what the "real" destination is. Therefore, we need a new message.

Usage

The router maintains a cache for the actual destination is used from a meta LS. When the client sends a message to a destination which resolves to a meta LS, the router checks the cache for the actual destination last used. If the cache is empty, the router selects a destination from the meta LS, and looks up the leaseset. If the leaseset lookup is successful, the router adds that destination to the cache, and sends the client a Meta Redirect Message. This is only done once, unless the destination expires and must be changed. The client must also cache the information if needed. The Meta Redirect Message is NOT sent in reply to every SendMessage.

The router only sends this message to clients with version 0.9.47 or higher.

The client does not send a reply to this message.

Message Type

The message type for the Meta Redirect Message is 43.

Format

Session ID (2 bytes) The value from the Send Message.
Message ID generated by the router (4 bytes)
4 byte nonce previously generated by the client
             (the value from the Send Message, may be zero)
Flags:       2 bytes, bit order 15...0
             Unused, set to 0 for future compatibility
             Bit 0: 0 - the destination is no longer meta
                    1 - the destination is now meta
             Bits 15-1: Unused, set to 0 for future compatibility
Original Destination (387+ bytes)
(following fields only present if flags bit 0 is 1)
MFlags:      2 bytes
             Unused, set to 0 for future compatibility
             From the Meta Lease for the actual Destination
Expiration:  4 bytes, big endian, seconds since epoch
             From the Meta Lease for the actual Destination
Cost (priority) 1 byte
             From the Meta Lease for the actual Destination
Actual (real) Destination (387+ bytes)