mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2025-03-10 09:10:07 +01:00
Code Issues Projects Releases Wiki Activity

BOLT 4: apply stylesheet updates, first pass copy edit to line 128

Browse source
This commit is contained in:
Landon Mutch 2017-11-27 19:16:32 -08:00 • committed by Rusty Russell
parent 5db55df16a
commit 7ce3341254
1 changed files with 41 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

77
04-onion-routing.md
View file

@ -65,29 +65,34 @@ A node:
# Conventions # Conventions
There are a number of conventions we will adhere to throughout the document: There are a number of conventions adhered to throughout this document:
- The maximum route length is limited to 20 hops. - The maximum route length is limited to 20 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. - HMAC: the integrity verification of the packet is based on Keyed-Hash
- Elliptic Curve: for all computations involving elliptic curves, the Message Authentication Code, as defined by the
Bitcoin curve, [`secp256k1`](http://www.secg.org/sec2-v2.pdf), is used. [FIPS 198 Standard](http://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf)/[RFC 2104](https://tools.ietf.org/html/rfc2104)
- Pseudo-Random Stream: [`ChaCha20`](https://tools.ietf.org/html/rfc7539) is used to generate a pseudo-random byte stream. and using a `SHA256` hashing algorithm.
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. - Elliptic curve: for all computations involving elliptic curves, the
- We use the terms _hop_ and _node_ interchangeably. Bitcoin curve is used, as specified in [`secp256k1`](http://www.secg.org/sec2-v2.pdf).
- A _peer_ is a direct neighbor of the processing node in the overlay network. - Pseudo-random stream: [`ChaCha20`](https://tools.ietf.org/html/rfc7539) is
used to generate a pseudo-random byte stream. For its generation, a fixed
null-nonce (`0x0000000000000000`) is used, along with a key derived from a
shared secret and a `0x00`-byte stream of the desired output size as the message.
- The terms _hop_ and _node_ are used interchangeably.
- The term _peer_ refers only to a direct neighbor (in the overlay network) of the processing node.
# Key Generation # Key Generation
A number of encryption and verification keys are derived from the shared secret: A number of encryption and verification keys are derived from the shared secret:
- _rho_: used as key when generating the pseudo-random byte stream - _rho_: used as key when generating the pseudo-random byte stream
used to obfuscate the per-hop information. used to obfuscate the per-hop information
- _mu_: used during the HMAC generation. - _mu_: used during the HMAC generation
- _um_: used during error reporting. - _um_: used during error reporting
The key generation takes a key-type (_rho_=`0x72686F`, _mu_=`0x6d75` or _um_=`0x756d`) and a 32 byte secret as inputs and returns a 32 byte key. The key generation takes a key-type (_rho_=`0x72686F`, _mu_=`0x6d75` or _um_=`0x756d`) 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 _um_, as HMAC-key and the 32 byte shared secret as the message. Keys are generated by computing an HMAC, with `SHA256` as hashing algorithm, using the key-type, i.e., _rho_, _mu_ or _um_, as HMAC-key and the 32-byte shared secret as the message.
The resulting HMAC is then returned as the key. 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 _rho_ key-type is 3 bytes, not 4. Notice that the key-type does not include a C-style `0x00` termination-byte, e.g., the length of the _rho_ key-type is 3 bytes, not 4.
@ -100,15 +105,15 @@ The use of a fixed nonce is safe since the keys are never reused.
# Packet Structure # Packet Structure
The packet consists of 4 parts: The packet consists of four parts:
- A `version` byte - a `version` byte
- A 33-byte compressed `secp256k1` `public_key`, used during the shared secret generation - a 33-byte compressed `secp256k1` `public_key`, used during the shared secret generation
- A 1300-byte `hops_data` consisting of twenty fixed size packets containing information for each hop - a 1300-byte `hops_data` consisting of 20 fixed size packets containing information for each hop
as they forward the message. as they forward the message
- A 32-byte `HMAC` used to verify the packet's integrity. - a 32-byte `HMAC` used to verify the packet's integrity
The overall structure of the packet is depicted below. The network format of the packet consists of the individual parts being serialized into one contiguous 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. The overall structure of the packet is depicted below. The network format of the packet consists of the individual parts being serialized into one contiguous 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.
1. type: `onion_packet` 1. type: `onion_packet`
2. data: 2. data:
@ -117,9 +122,9 @@ The overall structure of the packet is depicted below. The network format of the
* [`20*65`:`hops_data`] * [`20*65`:`hops_data`]
* [`32`:`hmac`] * [`32`:`hmac`]
For this specification `version` has a constant value of `0x00`. For this specification, `version` has a constant value of `0x00`.
The `hops_data` field is a structure that holds obfuscated versions of the next hop's address, transfer information and the associated HMAC. It is 1300 bytes long, and has the following structure: The `hops_data` field is a structure that holds obfuscated versions of the next hop's address, transfer information, and the associated HMAC. It is 1300 bytes long and has the following structure:
1. type: `hops_data` 1. type: `hops_data`
2. data: 2. data:
@ -182,7 +187,7 @@ Field Description:
Inclusion of this field allows a node to both authenticate the information Inclusion of this field allows a node to both authenticate the information
specified by the original sender and the parameters of the HTLC forwarded, specified by the original sender and the parameters of the HTLC forwarded,
and ensure the original sender is using the current `cltv_expiry_delta` value. and ensure the original sender is using the current `cltv_expiry_delta` value.
If there is no next hop, `cltv_expiry_delta` is zero. If there is no next hop, `cltv_expiry_delta` is 0.
If the values don't correspond, then the HTLC should be failed+rejected as If the values don't correspond, then the HTLC should be failed+rejected as
this indicates the incoming node has tampered with the intended HTLC this indicates the incoming node has tampered with the intended HTLC
values, or the origin has an obsolete `cltv_expiry_delta` value. values, or the origin has an obsolete `cltv_expiry_delta` value.
@ -215,7 +220,7 @@ See the [Returning Errors](#returning-errors) section below for more details.
Assuming a _sender node_ `n_0` wants to route a packet to a _final recipient_ `n_r`. 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 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 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`. 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. 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. Associated data will be included in the HMACs and has to match the associated data provided during integrity verification at each hop.
@ -237,12 +242,12 @@ This recursive algorithm is initialized by setting the first hop's (`k=1`) ephem
The sender then iteratively computes the ephemeral public keys, shared secrets and blinding factors for nodes `{n_2, ..., n_r}`. 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. 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` 65 byte `per_hop` payloads. 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` 65-byte `per_hop` payloads.
The construction returns one 1366 byte packet and the first hop's address. The construction returns a single 1366-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 packet construction is performed in reverse order of the route, i.e., the last hop's operations are applied first.
The packet is initialized with 1366 `0x00` bytes. The packet is initialized with 1366 `0x00`-bytes.
A 65-byte filler is generated with the shared secret: A 65-byte filler is generated with the shared secret:
See below for details on filler generation. See below for details on filler generation.
@ -351,12 +356,12 @@ Comparison of the computed HMAC and the HMAC from the packet MUST be time-consta
At this point the node can generate a _rho_-key and a _gamma_-key. 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. The routing info is deobfuscated and the information about the next hop is extracted.
In order to do so the node copies the `hops_data` field, appends 65 `0x00` bytes and generates 1365 pseudo-random bytes using the _rho_-key and applies it using `XOR` to the copy of the `hops_data` In order to do so the node copies the `hops_data` field, appends 65 `0x00`-bytes and generates 1365 pseudo-random bytes using the _rho_-key and applies it using `XOR` to the copy of the `hops_data`
The first 65 bytes of the resulting routing info are `per_hop` field for the next hop. The next 1300 bytes is the `hops_data` for the outgoing packet. The first 65 bytes of the resulting routing info are `per_hop` field for the next hop. The next 1300 bytes is the `hops_data` for the outgoing packet.
If the `realm` is unknown, then the node MUST drop the packet and signal a route failure. If the `realm` is unknown, then the node MUST drop the packet and signal a route failure.
A special `per_hop` `HMAC` value of 32 `0x00` bytes indicates that the currently processing hop is the intended recipient and that the packet should not be forwarded. A special `per_hop` `HMAC` value of 32 `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 `hops_data`. 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 `hops_data`.
The resulting packet is then forwarded to the addressed peer. The resulting packet is then forwarded to the addressed peer.
@ -367,8 +372,8 @@ Should the processing node not have a peer with the matching address, then it MU
The sender performs ECDH with each hop of the route in order to establish a 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. For each message a new _sessionkey_ is generated.
The sessionkey is a 32 byte EC private key. 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. 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 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 processing 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. In the processing 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.
@ -387,7 +392,7 @@ For this reason the field is padded before forwarding.
Since the padding is part of the HMAC the sender will have to generate an identical padding in order to compute the HMACs correctly for each hop. Since the padding is part of the HMAC the sender will have to generate an identical padding in order to compute the HMACs correctly for each hop.
The filler is also used to pad the field-length in case the selected route is shorter than the maximum allowed route length. The filler is also used to pad the field-length in case the selected route is shorter than the maximum allowed route length.
Before deobfuscating the `hops_data`, the node pads it with 65 `0x00` bytes, such that the total length is `(20 + 1) * 65`. Before deobfuscating the `hops_data`, the node pads it with 65 `0x00`-bytes, such that the total length is `(20 + 1) * 65`.
It then generates the pseudo-random byte stream of matching length and applies it with `XOR` to the `hops_data`. It then generates the pseudo-random byte stream of matching length and applies it with `XOR` to the `hops_data`.
This deobfuscates the information destined for it, and simultaneously obfuscates the added This deobfuscates the information destined for it, and simultaneously obfuscates the added
`0x00`-bytes at the end. `0x00`-bytes at the end.
@ -432,7 +437,7 @@ The last hop does not obfuscate the filler since it will not forward the packet
# Blinding EC Points # Blinding EC Points
In order to vary the ephemeral public key (the EC point) between hops, it is blinded at each hop. 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. 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. 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 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.
@ -478,7 +483,7 @@ The association between forward and return packet is handled outside of the prot
## Failure Messages ## Failure Messages
The failure message encapsulated in `failuremsg` has identical format to The failure message encapsulated in `failuremsg` has identical format to
a normal message: two byte type (`failure_code`) followed by data suitable a normal message: 2-byte type (`failure_code`) followed by data suitable
for that type. The following `failure_code` values are supported. for that type. The following `failure_code` values are supported.
A node MUST select one of these codes when creating an error message, and MUST include the appropriate data. A node MUST select one of these codes when creating an error message, and MUST include the appropriate data.
Notice that the `failure_code` are not message types defined in other BOLTs, not being sent directly on the transport layer, but wrapped inside an return packet. Notice that the `failure_code` are not message types defined in other BOLTs, not being sent directly on the transport layer, but wrapped inside an return packet.
@ -693,7 +698,7 @@ The following is an in-depth trace of the packet creation, including intermediat
sessionkey = 0x4141414141414141414141414141414141414141414141414141414141414141 sessionkey = 0x4141414141414141414141414141414141414141414141414141414141414141
associated data = 0x4242424242424242424242424242424242424242424242424242424242424242 associated data = 0x4242424242424242424242424242424242424242424242424242424242424242
The HMAC is omitted in the following `hop_data` since it is likely filled by the onion construction. Hence the values below are the `realm`, the `short_channel_id`, the `amt_to_forward`, the `outgoing_cltv` and the 16 bytes `padding`. These were initialized by byte-filling the `short_channel_id` to the respective position in the route, and by settings `amt_to_forward` and `outgoing_cltv` to the position in the route, starting with 0. The HMAC is omitted in the following `hop_data` since it is likely filled by the onion construction. Hence the values below are the `realm`, the `short_channel_id`, the `amt_to_forward`, the `outgoing_cltv` and the 16-bytes `padding`. These were initialized by byte-filling the `short_channel_id` to the respective position in the route, and by settings `amt_to_forward` and `outgoing_cltv` to the position in the route, starting with 0.
hop_payload[0] = 0x000000000000000000000000000000000000000000000000000000000000000000 hop_payload[0] = 0x000000000000000000000000000000000000000000000000000000000000000000
hop_payload[1] = 0x000101010101010101000000010000000100000000000000000000000000000000 hop_payload[1] = 0x000101010101010101000000010000000100000000000000000000000000000000
@ -770,7 +775,7 @@ The HMAC is omitted in the following `hop_data` since it is likely filled by the
## Returning Errors ## Returning Errors
We use the same parameters (node ids, shared secrets ,...) as above We use the same parameters (node IDs, shared secrets ,...) as above
# node 4 is returning an error # node 4 is returning an error
failure_message = 2002 failure_message = 2002