Problem statement

Reimplement RLPx protocol in Rust.

Technical Goals

The implementation focusses on following:-

1. Simplifying MAC egress/ingress validation.
2. Simplifying transport layer and codec definitions.
3. Updating secp256k1 crates to its latest version and its function signatures.
4. Adding handshake tests to make sure it communicates with latest geth client.

Hard Requirements

• The solution has to perform a full protocol-level (post-TCP/etc.) handshake with the target node.

Solution

The repository consists of a geth client which can spin up a local network in your machine. The other crate is a lightweight client performing the handshake with the geth client.

The handhake occurs in two phases:-

Phase I - Send auth and receive ack to/from recipient

Phase II - Send/Recv outbound message to/from recipient

The formulation for Phase I and II are adapted from source RLPx protocol

Phase I

Phase I is implemented by using a state machine to decode incoming data via codec and transition between different states of the handshake between peers.The implementation can be found in server/networking/codec.rs

The initial auth-ack handshake from source is defined as follows:-

auth = auth-size || enc-auth-body
auth-size = size of enc-auth-body, encoded as a big-endian 16-bit integer
auth-body = [sig, initiator-pubk, initiator-nonce...]
enc-auth-body = codec.encrypt(recipient-pubk, auth-body || auth-padding, auth-size)

ack = ack-size || enc-ack-body
ack-size = size of enc-ack-body, encoded as a big-endian 16-bit integer
ack-body = [recipient-ephemeral-pubk, recipient-nonce,...]
enc-ack-body = codec.encrypt(initiator-pubk, ack-body || ack-padding, ack-size)

Other cryptographic exhanges taking place in Phase I

1. Secrets generated following the exchange of auth-ack handshake messages.

   ephemeral-key = ecdh.agree(ephemeral-privkey, remote-ephemeral-pubk)
   shared-secret = keccak256(ephemeral-key || keccak256(nonce || initiator-nonce))
   aes-secret = keccak256(ephemeral-key || shared-secret)
   mac-secret = keccak256(ephemeral-key || aes-secret)
   

2. MAC: Message Authentication Code from initiator

   ingress-mac = keccak256.init((mac-secret ^ initiator-nonce) || ack)
   

   ingress mac is checked against mac bytes received from the header and body.

Phase II

After the auth-ack phase is complete an outbound message is sent to the recipient and it sends back a response which is deserialized back.

Prerequisites

The following service utilizes docker

• cargo: compiler for Rust. To install Rust you will need the following command.This will install rustup as well.

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
  

• gcc: required for libc bindings See here for installation options.

• docker and its utilities User requires to install Docker and Docker Compose(v2) on their machine. See Install Docker Engine on Ubuntu

  The following are the versions of the toolchain

  Toolchain	Version
  Ubuntu	22.04.3 LTS
  cargo	1.72.0 (103a7ff2e 2023-08-15)
  rustup	1.26.0
  gcc	11.4.0
  docker	24.0.5 build ced0996
  docker compose	v2.20.0

How to execute

1. Enable permissions on the run.sh file by performing

   chmod +x run.sh
   

2. Run run.sh file. You will be prompted to enter your password because docker compose needs to be run with admin privileges. You will get the following output.

   ./run.sh
   

   Output:-

    [+] Running 4/4
    ✔ Network geth_priv-eth-net           Crea...                             0.2s
    ✔ Container geth-geth-bootnode-1      Started                             1.0s
    ✔ Container geth-geth-rpc-endpoint-1  Started                             1.8s
    ✔ Container geth-geth-miner-1         St...                               1.6s
        Finished test [unoptimized + debuginfo] target(s) in 0.08s
        Running unittests src/lib.rs (target/debug/deps/rlpx_handshake-31be7cfd58185a34)
   
    running 2 tests
    test tests::test_handshake_failure_with_incorrect_id ... ok
    test tests::test_handshake_success ... ok
   
    test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.02s
   

3. Please run the cleanup.sh command in order to clean up artifacts to save resources.

   ./cleanup.sh
   

How to know if handshake is successful

The only way to know if the handshake is successful is

1. To check if the geth recipient node sends back its client version and its current protocol version at the end of the handshake in Phase II after the initiator sends a Hello frame with its own client and protocol version.

   In this case the recipient client version: Geth/v1.10.1-stable-c2d2f4ed/linux-amd64/go1.16 and the protocol version is 5.

2. To check if the the handshake fails when we use a different public key other than the actual node public key.

   In this case the node public key defined in docker compose setupfor geth node: af22c29c316ad069cf48a09a4ad5cf04a251b411e45098888d114c6dd7f489a13786620d5953738762afa13711d4ffb3b19aa5de772d8af72f851f7e9c5b164a

Two tests test tests::test_handshake_failure_with_incorrect_id and test tests::test_handshake_success are defined two test (1) and (2).