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.

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

The unsafe_code lint is set to forbid which means that unsafe code is not allowed (unless through a third-party crate).

Nearly all of the code within the listen loop of the server is panic free to prevent the server from crashing from a bad request.

Performance

A significant amount of work has been put into optimizing the code. Learn more and see benchmark results on our wiki, or run the benchmarks yourself with cargo benches.

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.
• Docker is used to automate testing the server binary with both the client binary and third-party dhcp clients (currently dhclient). Run with docker compose up --build.
• All code changes are tested on a real router before being released.

Status

Currently, only dhcpv4/ipv4 is handled. Ipv6 support will be added in the future.

The standard RFCs are closely followed, but its hard to promise 100% compatibility with them. Subtle differences may exist.

The message library code is complete with the exception of needing to implement more options.

The server library/binary have successfully assigned/validated an ip address on a router. The server is currently single threaded, configured through a toml file, and leases are stored in another toml file.

The client binary is still a work in progress, but the client library code is more complete.

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.

Releasing

0. If this is a hotfix, branch off the previous release (git switch -C hotfix/v0.5.1 tags/v0.5.0)
1. Update the version in Cargo.toml.
2. Check the CHANGELOG.md.
3. Commit/Push the changes.
4. Create/Push an annotated tag (with the SHA of the last commit): git tag -a v0.2.1 aa15cb8473 -m "v0.2.1" && git push --tags origin.
5. Publish to crates.io: cargo publish.

License

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