From 7ce3341254539d3276be6f26ed7adb09161c934d Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Mon, 27 Nov 2017 19:16:32 -0800 Subject: [PATCH] BOLT 4: apply stylesheet updates, first pass copy edit to line 128 --- 04-onion-routing.md | 77 ++++++++++++++++++++++++--------------------- 1 file changed, 41 insertions(+), 36 deletions(-) diff --git a/04-onion-routing.md b/04-onion-routing.md index 85861e5..27b0f21 100644 --- a/04-onion-routing.md +++ b/04-onion-routing.md @@ -65,29 +65,34 @@ A node: # 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. - - 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. - - 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. + - 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) + and using a `SHA256` hashing algorithm. + - Elliptic curve: for all computations involving elliptic curves, the + Bitcoin curve is used, as specified in [`secp256k1`](http://www.secg.org/sec2-v2.pdf). + - 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 A number of encryption and verification keys are derived from the shared secret: - _rho_: used as key when generating the pseudo-random byte stream - used to obfuscate the per-hop information. - - _mu_: used during the HMAC generation. - - _um_: used during error reporting. + used to obfuscate the per-hop information + - _mu_: used during the HMAC generation + - _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. 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 -The packet consists of 4 parts: +The packet consists of four parts: - - A `version` byte - - 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 - as they forward the message. - - A 32-byte `HMAC` used to verify the packet's integrity. + - a `version` byte + - a 33-byte compressed `secp256k1` `public_key`, used during the shared secret generation + - a 1300-byte `hops_data` consisting of 20 fixed size packets containing information for each hop + as they forward the message + - 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` 2. data: @@ -117,9 +122,9 @@ The overall structure of the packet is depicted below. The network format of the * [`20*65`:`hops_data`] * [`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` 2. data: @@ -182,7 +187,7 @@ Field Description: Inclusion of this field allows a node to both authenticate the information 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. - 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 this indicates the incoming node has tampered with the intended HTLC 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`. 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`. +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. @@ -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}`. 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. -The construction returns one 1366 byte packet and the first hop's address. +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 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 is initialized with 1366 `0x00` bytes. +The packet is initialized with 1366 `0x00`-bytes. A 65-byte filler is generated with the shared secret: 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. 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. 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`. 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. 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. +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 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. 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`. This deobfuscates the information destined for it, and simultaneously obfuscates the added `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 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. 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 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. 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. @@ -693,7 +698,7 @@ The following is an in-depth trace of the packet creation, including intermediat sessionkey = 0x4141414141414141414141414141414141414141414141414141414141414141 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[1] = 0x000101010101010101000000010000000100000000000000000000000000000000 @@ -770,7 +775,7 @@ The HMAC is omitted in the following `hop_data` since it is likely filled by the ## 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 failure_message = 2002