Developer Guide

If you are familiar with Rust, hacking on the apple-codesign crate should feel like any other Rust crate. But there are a few things to watch out for:

  • The smartcard crate feature isn’t enabled by default because it pulls in library dependencies on Linux that aren’t always present. We recommend testing with --all-features to ensure all code in the crate is exercised.

  • There is some conditional code when running on macOS. We’ve tried to isolate that code to the macos file/module so changes are more obvious.

  • When running tests on macOS, some tests call out to Apple tools (like csreq). Non-standard system installs or 3rd party tools on PATH may confuse tests. (We generally consider these bugs in the tests and if you see a test failure due to a runtime environment issue, please file a bug or send a patch to fix.)

Desire for Determinism and Reproducibility

As much code and behavior should be deterministic and bit-for-bit reproducible as possible. There are some obvious cases where bits will disagree (such as time-stamp tokens from remote timestamp servers). But we strive for the same data inputs to produce the same output as much as possible. Unless it can’t be avoided due to the fundamental nature of an operation (such as a random/remote operation), we consider non-determinism to be a bug.

Desire for Compliance with Apple Tooling

We bias towards Apple’s official tooling to define behavior.

Generally, if our implementation behaves differently from Apple’s official tooling in a meaningful way (definition of meaningful is subject to interpretation), the default behavior should be to treat this as a bug. If deviation is desirable, the justifications should be documented. Ideally in this documentation tree or in inline code comments. But commit messages are also fine. The important thing is we leave a breadcrumb trail of known deviations and why they exist.

There are plenty of valid reasons to deviate from behavior of Apple’s tooling. We purposefully let present and future project maintainers interpret valid reasons as they want.