Something went wrong. Try again.
DKIM (RFC 6376) signing and verification for Zig 0.16: both canonicalizations, RSA and Ed25519, no I/O or allocation.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
const std = @import("std");
pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{});
const std_crypto_ext = b.dependency("std_crypto_ext", .{ .target = target, .optimize = optimize, });
const mod = b.addModule("dkim", .{ .root_source_file = b.path("src/root.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "std_crypto_ext", .module = std_crypto_ext.module("std_crypto_ext") }, }, });
// The command-line tool, which is both something useful and the harness // `tests/interop` drives another implementation against. const exe = b.addExecutable(.{ .name = "zig-dkim", .root_module = b.createModule(.{ .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "dkim", .module = mod }, .{ .name = "std_crypto_ext", .module = std_crypto_ext.module("std_crypto_ext") }, }, }), }); b.installArtifact(exe);
const run_cmd = b.addRunArtifact(exe); run_cmd.step.dependOn(b.getInstallStep()); run_cmd.stdio = .inherit; run_cmd.addPassthruArgs(); const run_step = b.step("run", "Run the command-line signer and verifier"); run_step.dependOn(&run_cmd.step);
// A test executable covers one module, so each needs its own. Missing one // out would not fail: its tests would simply never run. const test_step = b.step("test", "Run tests"); for ([_]*std.Build.Module{ mod, exe.root_module }) |m| { test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = m })).step); }
// The end-to-end tests sign a message with one half of this library and // verify it with the other, which is the only test that can catch the two // halves agreeing with each other and with nobody else. They are a module // of their own so that a consumer never compiles them, and so that they // can hold the test key material. const e2e_mod = b.createModule(.{ .root_source_file = b.path("tests/e2e.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "dkim", .module = mod }, .{ .name = "std_crypto_ext", .module = std_crypto_ext.module("std_crypto_ext") }, }, }); test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = e2e_mod })).step);
// The fuzz targets: what the parsers and the canonicalizers must do with // input nobody wrote, which for a DKIM verifier is all of it. They are // ordinary tests as well as fuzz tests, so `zig build test` exercises the // same properties on the seeds checked in beside them. const fuzz_mod = b.createModule(.{ .root_source_file = b.path("tests/fuzz.zig"), .target = target, .optimize = optimize, .imports = &.{.{ .name = "dkim", .module = mod }}, }); // Zig's fuzzer takes one test at a time and keeps a coverage file per // test, so naming a target is what you want when a finding is being // chased: `zig build fuzz --fuzz -Dfuzz-filter=canonical`. const fuzz_filter = b.option( []const u8, "fuzz-filter", "Fuzz or test only the targets whose name contains this", ); // LLVM, because the self-hosted backend Debug uses by default emits no // coverage instrumentation: under it the fuzzer's table of program // counters comes back empty and `--fuzz` fails in the build runner rather // than fuzzing anything. `build.zig` cannot see whether `--fuzz` was // passed, so it is always on. const fuzz_tests = b.addTest(.{ .root_module = fuzz_mod, .filters = if (fuzz_filter) |f| &.{f} else &.{}, .use_llvm = true, }); test_step.dependOn(&b.addRunArtifact(fuzz_tests).step);
// A step of its own for `zig build fuzz --fuzz`, which needs a run step // holding nothing else: the fuzzer takes over the terminal and runs until // it is stopped, so it must not be reached by `zig build test`. const fuzz_step = b.step("fuzz", "The fuzz targets: add --fuzz to fuzz them"); fuzz_step.dependOn(&b.addRunArtifact(fuzz_tests).step);
// The loop that drives those same targets without Zig's fuzzer: no // coverage feedback, but the same run on every machine for a given seed, // which is what CI wants. `tools/fuzz.zig` says more. Optimised, because // a fuzzer's whole job is how many inputs it gets through, and // ReleaseSafe keeps every check that makes a failure a failure. const fuzz_run = b.addExecutable(.{ .name = "zig-dkim-fuzz", .root_module = b.createModule(.{ .root_source_file = b.path("tools/fuzz.zig"), .target = b.graph.host, .optimize = .ReleaseSafe, .imports = &.{.{ .name = "fuzz_targets", .module = fuzz_mod }}, }), }); const run_fuzz = b.addRunArtifact(fuzz_run); run_fuzz.stdio = .inherit; run_fuzz.addPassthruArgs(); const fuzz_run_step = b.step("fuzz-run", "Fuzz the targets with a loop of our own"); fuzz_run_step.dependOn(&run_fuzz.step);
// Interoperability with other people's implementations, which is the only // evidence that this library is right rather than merely self-consistent: // a signer and a verifier that are wrong in the same way agree with each // other perfectly. It is not part of `zig build test` because it needs // `dkimpy` and `opendkim` from the devshell rather than a Zig toolchain, // and because it is slow enough to be worth running on purpose. const interop = b.addSystemCommand(&.{ "python3", "tests/interop/run.py" }); interop.step.dependOn(b.getInstallStep()); interop.stdio = .inherit; // It shells out to the built binary, so it must not be cached on its // inputs -- the binary changing is the whole point of running it again. interop.has_side_effects = true; const interop_step = b.step("interop", "Sign and verify against dkimpy and opendkim"); interop_step.dependOn(&interop.step);
// Nothing else builds these, so without this they could stop compiling and // `zig build test` would not notice. const check_step = b.step("check", "Compile everything without running it"); check_step.dependOn(&fuzz_run.step);
// -- documentation ------------------------------------------------------- // // Zig emits the API documentation as a side effect of compiling, so the // module is built as a library purely to get at it. What comes out is not // a page but a program: a WebAssembly viewer, its javascript, and a tar of // the sources it reads from. const library = b.addLibrary(.{ .name = "dkim", .root_module = mod }); const install_docs = b.addInstallDirectory(.{ .source_dir = library.getEmittedDocs(), .install_dir = .prefix, .install_subdir = "docs", }); const docs_step = b.step("docs", "Build the API documentation into zig-out/docs"); docs_step.dependOn(&install_docs.step);
// That viewer fetches `sources.tar` and `main.wasm` at runtime, which a // browser refuses to do from a `file://` page, so reading the docs // locally means serving them. It is the same reason `zig std` runs a // server rather than opening a file. const docs_port = b.option(u16, "docs-port", "Port for `zig build docs-serve` (default 8000)") orelse 8000;
const docs_server = b.addExecutable(.{ .name = "docs-server", .root_module = b.createModule(.{ .root_source_file = b.path("tools/docs_server.zig"), // Always built for the machine running the build, never for // whatever -Dtarget the library is being built for. .target = b.graph.host, .optimize = .Debug, }), });
const run_docs_server = b.addRunArtifact(docs_server); run_docs_server.step.dependOn(&install_docs.step); run_docs_server.addDirectoryArg(library.getEmittedDocs()); run_docs_server.addArg(b.fmt("{d}", .{docs_port})); // The server runs until interrupted, so its output has to reach the // terminal rather than being captured by the build runner. run_docs_server.stdio = .inherit;
const docs_serve_step = b.step("docs-serve", "Serve the API documentation over HTTP"); docs_serve_step.dependOn(&run_docs_server.step);
// The server has tests of its own; without this they would never run. test_step.dependOn(&b.addRunArtifact( b.addTest(.{ .root_module = docs_server.root_module }), ).step); check_step.dependOn(&docs_server.step);}