This is a Rust implementation of the OmniBOR specification, which defines a reproducible identifier scheme and a fine-grained build dependency tracking mechanism for software artifacts.

The goal for OmniBOR is to be incorporated into software build tools, linkers, and more, so software consumers can:

• Reproducibly identify software artifacts;
• Deeply inspect all the components used to construct a software artifact, beyond just what packages are in a dependency tree;
• Detect when dependencies change through updated artifact identifiers.

The last point is key: Artifact ID's incorporate dependency information, forming a variant of a Merkle Tree! This Directed Acyclic Graph (DAG) of dependencies cascades up evidence of artifact dependency changes, enabling consumers of software artifacts to know when changes happen, and what precisely has changed.

[!IMPORTANT] The OmniBOR spec, and this Rust package, are still a work-in-progress. This also means it's a great time to contribute!

If you want to contribute to the specification instead, check out the OmniBOR spec repository.

Using

Using from Rust

Run the following to add the library to your own crate.

$ cargo add omnibor

The omnibor crate currently exposes the following features:

To turn on a feature, you can run cargo add omnibor --features="<feature name>", or edit your Cargo.toml to activate the feature.

Using from other languages

The omnibor crate is designed to also be used from other programming languages!

All API's in the crate are exposed over a Foreign Function Interface, usable by anything that can consume C code.

The crate is configured to produce files suitable for either static or dynamic linking with non-Rust code. Additionally, you'll need to use cbindgen to produce a header file which describes the contents of the linkable library.

Testing

omnibor provides a variety of tests, which can be run with cargo test. To ensure serialization and deserialization code are tested as well, run cargo test --features="serde".

Design

The OmniBOR Rust implementation is designed with the following goals in mind:

• Cross-language readiness: The OmniBOR Rust implementation should be built with solid Foreign Function Interface (FFI) support, so it can be used as the basis for libraries in other languages.
• Multi-platform: The OmniBOR Rust implementation should be ready for use in as many contexts as possible, including embedded environments. This means supporting use without an allocator to dynamically allocate memory, and minimizing the size of any types resident in memory.
• Fast: The OmniBOR Rust implementation should run as quickly as possible, and be designed for high-performance use cases like rapid large scale matching of artifacts to identifiers.
• Memory efficient: The OmniBor data is designed to be of minimal size in memory, with the understanding that real-world uses of omnibor are likely to work with large number of identifiers at a time. For example, the type ArtifactId<Sha256> is exactly 32 bytes, just the number of bytes necessary to store the SHA-256 hash.

Usage in no_std environments is currently planned but not yet implemented.

Stability Policy

omnibor does intend to follow semantic versioning when publishing new versions. It is currently pre-1.0, which for us means we do not generally aim for stability of the APIs exposed, as we are still iterating and designing what we consider to be an ideal API for future stabilization.

That said, we do not break stability in point releases.

New version inferences are supported by the use of conventional commits which mark the introduction of new features or fixing of bugs. When new releases of omnibor are made, git-cliff checks our requested version bump against its determination of the correct version bump based on the CHANGELOG.md, and produces a release error if it believes we're requesting to bump the wrong version. This helps defend against accidentally-incorrect version bumps which would violate semantic versioning.

Minimum Supported Rust Version (MSRV)

This crate does not maintain a Minimum Supported Rust Version, and generally tracks the latest Rust stable version.

Contributing

We recommend checking out the full CONTRIBUTING.md for the OmniBOR Rust project, which outlines our process.

License

All of the OmniBOR Rust implementation is Apache 2.0 licensed. Contributions to omnibor are assumed to be made in compliance with the Apache 2.0 license.