This document describes the construction of an onion routed packet that is used to route a payment from a _origin node_ to a _final node_, over a number of intermediate nodes, called _hops_.
- HMAC: the integrity verification of the packet is based on Keyed-Hash Message Authentication Code as defined by the [FIPS 198 Standard](http://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf)/[RFC 2104](https://tools.ietf.org/html/rfc2104), using `SHA256` as hashing algorithm.
The resulting HMAC is then truncated at 20 bytes in order to reduce the overhead.
- Elliptic Curve: for all computations involving elliptic curves, the
Bitcoin curve, [`secp256k1`](http://www.secg.org/sec2-v2.pdf), is used.
- Pseudo-Random Stream: [`ChaCha20`](https://tools.ietf.org/html/rfc7539) is used to generate a pseudo-random byte stream.
For the generation we use a fixed null-nonce (`0x0000000000000000`), a key derived from a shared secret and a `0x00`-byte stream of the desired output size as message.
- We use the terms _hop_ and _node_ interchangeably.
- A _peer_ is a direct neighbor of the processing node in the overlay network.
The key generation takes a key-type (_rho_=`0x72686F`, _gamma_=`0x67616d6d61` or _mu_=`0x6d75`) and a 32 byte secret as inputs and returns a 32 byte key.
Keys are generated by computing an HMAC, with `SHA256` as hashing algorithm, using the key-type, i.e., _rho_, _mu_ or _gamma_, as HMAC-key and the 32 byte shared secret as the message.
The resulting HMAC is then returned as the key.
Notice that the key-type does not include a C-style `0x00` termination-byte, e.g., the length of the _gamma_ key-type is 5 bytes, not 6.
The pseudo-random byte stream is used to obfuscate the packet at each hop of the path, so that each hop may only recover the address of the next hop as well as the HMAC for the next hop.
The pseudo-random byte stream is generated by encrypting a `0x00`-byte stream of the required length with `ChaCha20`, initialized with a key derived from the shared secret and a zero-nonce (`0x00000000000000`).
The use of a fixed nonce is safe since the keys are never reused.
## Packet Structure
The packet consists of 2 parts:
- The fixed size _header_ containing meta information about the
packet and the routing information necessary to forward the
message.
- A fixed size _per-hop payload_ containing information for each hop
as they forward the message.
The overall structure of the packet is depicted below. The network format of the packet consists of the individual parts being serialized into one continguous byte-stream and then transferred to the recipient of the packet. Due to the fixed size of the packet it does not need to be prefixed by its length when transferred over a connection.
~~~~
+--------+-----------------+
| header | per-hop payload |
+--------+-----------------+
~~~~
The header is a fixed 854 byte array containing the necessary information for each hop to identify the next hop, and verify the integrity of the packet.
It consists of a version byte, a 33 byte compressed `secp256k1` public key, used during the shared secret generation, a 20 byte HMAC used to verify the packet's integrity and an 800 byte routing information field.
Assuming a _sender node_`n_0` wants to route a packet to a _final recipient_`n_r`.
The sender computes a route `{n_0, n_1, ..., n_{r-1}, n_r}`, where `n_0` is the sender itself and `n_r` is the final recipient.
The nodes `n_i` and `n_{i+1}` MUST be peers in the overlay network.
The sender gathers the public keys for `n_1` to `n_r` and generates a random 32 byte `sessionkey`.
Optionally the sender may pass in _associated data_, i.e., data that the packet commits to, but is not included in the packet itself.
Associated data will be included in the HMACs and has to match the associated data provided during integrity verification at each hop.
For each node the sender computes an _ephemeral public key_, a _shared secret_ and a _blinding factor_.
The blinding factor is used at each hop to blind the ephemeral public key for the next hop.
The node receiving the header will perform ECDH with the ephemeral public key and its private key to derive the same shared secret.
However, when generating the packet we do not have access to the node's private key.
Hence, we use the commutative property of multiplication and blind the node's public key with all previous blinding factors and perform ECDH using the node's blinded public key and the `sessionkey`.
The transformations at hop `k` are given by the following:
- The shared secret `ss_k` is computed by first blinding the node's public key `nodepk_k` with all previous blinding factors `{b_1, ..., b_{k-1}}`, if any, and then executing ECDH with the blinded public key and the `sessionkey`.
- The blinding factor is the `SHA256` hash of the concatenation between the node's public key `nodepk_k` and the hop's shared secret `ss_k`.
Before concatenation the node's public key is serialized in the compressed format.
- The ephemeral public key `epk_k` is computed by blinding the previous hop's ephemeral public key `epk_{k-1}` with the previous hop's blinding factor `b_{k-1}`.
This recursive algorithm is initialized by setting the first hop's (`k=1`) ephemeral public key to the public key corresponding with the `sessionkey`, i.e., `secp256k1` is used to derive a public key for the randomly selected `sessionkey`.
The sender then iteratively computes the ephemeral public keys, shared secrets and blinding factors for nodes `{n_2, ..., n_r}`.
Once the sender has all the required information it can construct the packet.
Constructing a packet routed over `r` hops requires `r` 32 byte ephemeral public keys, `r` 32 byte shared secrets, `r` 32 byte blinding factors and `r` 20 byte per-hop payloads.
The construction returns one 1254 byte packet and the first hop's address.
The packet construction is performed in reverse order of the route, i.e., the last hop's operations are applied first.
The per-hop payload is initialized with 400 `0x00` bytes.
The routing info is initialized with 800 `0x00` bytes.
The next address and the HMAC are initialized to 20 `0x00` bytes each.
Two fillers are generated with the shared secrets: a routing info filler with 40 byte hopsize and a per-hop payload filler with 20 byte hopsize.
See below for details on filler generation.
For each hop in the route in reverse order the sender applies the
following operations:
- It generates a _rho_-key, _mu_-key and a _gamma_-key using the hop's shared secret.
- The routing info field is right-shifted by 40 bytes, discarding the last 40 bytes that exceed the 800 bytes.
The address is copied into the first 20 bytes of the routing info and the HMAC is copied into
Should this be the last hop then the tail of the per-hop payloads field is overwritten with the per-hop payload filler.
- The next HMAC is computed over the concatenated routing info, per-hop payload and associated data, with the _mu_-key as HMAC-key.
- The next address is computed from the current node's public key using the Bitcoin address hash derivation.
The final value for the HMAC is the HMAC as it should be sent to the first hop.
The packet generation returns the serialized packet, consisting of the version byte, the ephemeral pubkey for the first hop, the HMAC for the first hop, the obfuscated routing info and the obfuscated per-hop payload.
The following code implements the packet construction in Go:
The receiving node then splits the packet into its fields.
The node MUST check that the ephemeral public key is on the `secp256k1` curve.
Should this not be the case the node MUST abort processing the packet and report a route failure to the sender.
The node then computes the shared secret as described below, using the private key corresponding to its public key and the ephemeral key from the packet.
The node MUST keep a log of previously used shared secrets.
Should the shared secret already be in the log it MUST abort processing the packet and report a route failure, since this is likely a replay attack, otherwise the shared secret is added to the log.
The shared secret is used to compute a _mu_-key. The node then computes the HMAC of the packet, starting from byte 54, which corresponds to the routing info, per-hop payloads and associated data, using the _mu_-key.
The resulting HMAC is compared with the HMAC from the packet.
Should the computed HMAC and the HMAC from the packet differ then the node MUST abort processing and report a route failure.
Comparison of the computed HMAC and the HMAC from the packet MUST be time-constant to avoid leaking information.
At this point the node can generate a _rho_-key and a _gamma_-key.
The routing info is deobfuscated and the information about the next hop is extracted.
In order to do so the node copies the routing info field, appends 40 `0x00` bytes and generates 840 pseudo-random bytes using the _rho_-key and applies it using `XOR` to the copy of the routing information.
The first 20 bytes of the padded copy are the node's per-hop payload, while the remaining 400 bytes are the per-hop payload destined for the next hop.
A special HMAC value of 20 `0x00` bytes indicates that the currently processing hop is the intended recipient and that the packet should not be forwarded.
Should the HMAC not indicate route termination and the next hop be a peer of the current node, then the new packet is assembled by blinding the ephemeral key with the current node's public key and shared secret, and serializing the routing info and per-hop payload.
The resulting packet is then forwarded to the addressed peer.
The addressed peer MUST be a direct neighbor of the node processing the packet.
Should the processing node not have a peer with the matching address, then it MUST drop the packet and signal a route failure.
## Shared secret
The sender performs ECDH with each hop of the route in order to establish a secret.
For each message a new _sessionkey_ is generated.
The sessionkey is a 32 byte EC private key.
The shared secret creation receives a public key and a 32 byte secret as input and returns a 32 byte secret as output.
In the packet generation phase the secret is the `sessionkey` and the public key is the node's public key, blinded with all previous blinding factors.
In the pocessing phase the secret is the node's private key and the public key is the ephemeral public key from the packet, which has been incrementally blinded by the predecessors.
The public key is multiplied by the secret, using to the `secp256k1` curve.
// Cut filler down to the correct length (numHops+1)*hopSize
// bytes will be prepended by the packet generation.
return filler[(numMaxHops-numHops+2)*hopSize:]
}
```
Notice that this implementation is for demonstration purposes only, the filler can be generated much more efficiently.
The last hop does not obfuscate the filler since it will not forward the packet and will not extract an HMAC for any followup hops.
## Blinding EC Points
In order to vary the ephemeral public key (the EC point) between hops, it is blinded at each hop.
The inputs for the blinding process are the EC point to be blinded, the node's public key and a 32 byte shared secret, while the output is a single EC point, representing the blinded element.
Blinding is done by computing a blinding factor from the node's public key and the shared secret for that hop.
The blinding factor is the result of serializing the node's public key into its compressed format, appending the shared secret and computing the `SHA256` hash.
The blinded EC point then is the result of the scalar multiplication between the EC point and the blinding factor.
The protocol includes a simple mechanism to return encrypted error messages to the origin node.
The returned messages may either be failures reported by any intermediate hop, or the final node.
The format of the forward packet is not usable for the return path, since no node other than the origin has the required information. Note that these error messages are not reliable, as they are not placed on-chain in the case of node failure.
In addition each node locally stores the previous hop it received the forward packet from, in order to determine where to send an eventual return packet.
The node returning the message builds a return packet consisting of the following fields:
Where `hmac` is an HMAC authenticating the remainder of the packet, with a key using the above key generation with key type "_um_", `failure-code` and `additional` are defined below, and `pad` as extra bytes to conceal length.
The obfuscation step is repeated by every node on the return path.
Upon receiving a packet the node will generate its `ammag`, generate the pseudo-random byte stream and apply it to the packet before forwarding.
The origin node detects that it is the final hop of the return message since it was the origin of the corresponding forward packet.
Having the shared secrets of all intermediate nodes it can unwrap the packet until the HMAC is a valid HMAC for the packet, which also identifies the sender of the return message.
The association between forward and return packet is handled outside of the protocol, e.g., by association to an HTLC in a payment channel.
