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.

This crate is heavily documented on docs.rs.

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.

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 and integration tests exist but more should be written.
• Docker is used to automate testing the server with third-party dhcp clients (currently dhclient).
• 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

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.