Toe Beans

This crate provides:

• A library for:
  • Serializing and deserializing DHCP messages.
  • Client and server logic.
• A client and server binary that wraps the library.

[!IMPORTANT] I'm looking for a remote Rust job. If you can help, please email me at employ_jon@pm.me

Usage

Library

cargo add toe-beans to install it as a dependency.

You may disable either of the default feature flags (v4_client/v4_server) if you don't need the other.

Check out the binaries' code and the docs.rs link above for examples of how to use the library.

Binary

cargo install toe-beans will install both the server and client binaries.

You may use the --bin cli arg to install only one of the binaries.

Check out this wifi router that uses the server binary.

Documentation

All versions of this crate are on docs.rs.

Or you may locally (offline):

• See the latest version's documentation with cargo doc --open
• Branch off any release tag with git switch -C <branch-name> <release-tag> then run cargo doc --open.
• Expore the DHCP RFC specifications downloaded to the /rfcs directory of this repo.
• Get a summary of historical changes by version from the /CHANGELOG.md file in this repo.

Safety and Stability

This is fully safe code (no use of unsafe), and is enforced with the unsafe_code lint set to forbid. Note that this lint does not prevent libraries from having unsafe code. Safe code will be chosen over unsafe code even where the unsafe code is faster.

Nearly all of the code within the request handling loop of the server has been verified to be panic free to prevent the server from crashing from a bad request. All encoding and decoding is verified panic free.

Performance

A significant amount of work has been put into optimizing the code. Learn more and see the results on our wiki, or:

• Run the benchmarks yourself with the cargo benches cargo alias.
• Run the load testing with docker compose up --build in the /docker/perfdhcp folder.

Testing

• Unit tests, doc tests, and integration tests can all be run through the cargo tests cargo alias. The integration tests check the server and client libraries.
• First-party and third-party testing of dhcp clients (currently dhclient and perfdhcp) is done with docker. Run a client by going to its folder in /docker and run docker compose up --build.
• Instead of a pipeline, each push is checked by a git hook. If you are developing this project, set it up with: git config --local core.hooksPath .githooks/.
• All changes are tested on a real router with real devices.

Status

The project is being actively developed. See more on the wiki.

Alternatives

[!WARNING] I have neither used, nor vetted the safety of any of these alternatives. There might be better options that I'm not aware of.

There were not a lot of dhcp libraries available when I started writing toe-beans. Nowadays there are more options, but to varying degrees of completeness.

• dhcproto has the most downloads (is a dhcp library only).
• DHCPlayer let you pentest dhcp with various known attacks.
• leasehund has no_std/embedded support.

You might also like...

Our other projects on https://black-cat.us.

License

Distributed under the terms of the GNU Library General Public License (Version 2.0). See LICENSE file for more information.