# 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](https://codeberg.org/black-cat/toe-beans/src/branch/main/src/bin) 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](https://codeberg.org/black-cat/antennas/src/branch/main/rust/src/toe_beans.rs) that uses the server binary.

## Documentation

All versions of this crate are on [docs.rs](https://docs.rs/toe-beans).

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](https://doc.rust-lang.org/std/keyword.unsafe.html)), 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](https://codeberg.org/black-cat/toe-beans/wiki/Performance), 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](https://codeberg.org/black-cat/antennas) with real devices.

## Status

The project is being actively developed. See more [on the wiki](https://codeberg.org/black-cat/toe-beans/wiki/Project-Status).

## 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](https://crates.io/crates/dhcproto) has the most downloads (is a dhcp library only).
- [DHCPlayer](https://crates.io/crates/dhcplayer) let you pentest dhcp with various known attacks.
- [leasehund](https://github.com/rttfd/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.
