Crate darkbio_trust

Expand description

§Ecosystem Roots of Trust in Rust

This crate holds the root pubkeys of the Dark Bio ecosystem and the attestation formats issued under them, so that any party can verify the identity of an Ark enclave or of the Dark Bio cloud with nothing beyond the public keys published in our transparency reports repository.

The crate has three parts:

roots embeds the keys and knows every root by fingerprint.
cloud verifies the attestations of the Dark Bio rotating cloud keys.
device verifies the attestations of Arks, hardware and emulated alike.

§Environments and features

Devices and clouds belong to one of three environments: release, staging and develop, each with its own roots. Every environment can be named in every Rust feature combination, but its keys are only embedded when the crate feature of the same name is enabled. No environment feature is enabled by default. Verification uses the roots supplied by the caller.

[dependencies]
darkbio-trust = { version = "0.5", features = ["release"] }

Hardware and emulated Arks live in separate realms. Hardware devices are attested once at manufacturing by the device root of their series and never expire. Emulated devices are attested online by the emulator root and always expire. The two realms never share trust.

§Verifying a device

Pass the root pubkeys you accept (hardware, emulator, or both), along with the current time.

use darkbio_trust::{Environment, device, roots};

fn authenticate(attestation: &[u8], now: u64) -> Result<device::Device, darkbio_trust::Error> {
    let env = Environment::Release;

    device::verify(
        attestation,
        roots::hardware(env),
        roots::emulator(env),
        Some(now),
    )
}

The result carries the identity key of the device, its serial, manufacturer, model and hardware revision, the time of issuance and, for emulated devices, the expiry. An attestation only proves that a root vouched for the key. The transport still has to prove that the peer holds it.

A device that was never onboarded presents an attestation signed by its own identity key. device::verify_self_signed accepts such an attestation and returns nothing but that key. Whether to talk to such a device is up to the application.

§Verifying the cloud

The cloud root of an environment attests the cloud’s current signing and encryption keys. cloud::verify_signer and cloud::verify_crypto take that root and return the claims, which name the operator, the endpoint the key serves, the key itself and its validity.

use darkbio_trust::{Environment, cloud, roots};

fn cloud_signer(attestation: &[u8], now: u64) -> Result<cloud::SignerClaims, Box<dyn std::error::Error>> {
    let root = roots::cloud(Environment::Release).ok_or("release roots are not embedded")?;

    let claims = cloud::verify_signer(attestation, root, Some(now))?;
    if claims.sub.sub != "https://api.dark.bio" {
        return Err("key serves another endpoint".into());
    }
    Ok(claims)
}

§Validity footnotes

Verification always checks the signature, the domain and the shape of the claims. Emulator attestations may be valid for at most 30 days; cloud attestations for at most 90 days; hardware attestations never expire. With a time specified, the attestation must also be valid at that moment. Without one, the clock check is skipped.

§Naming a signer

When an attestation names a key that is not among the roots passed in, the error identifies it if it is a root of the ecosystem. For example, a develop Ark presented to a release verifier would name a develop device or emulator attester. This is an unauthenticated hint for logs. The fingerprints of every root are compiled into every build, so a root can be named even when its key is not embedded. roots::identify answers the same question for RSA and xDSA fingerprints, the RSA secure boot keys included.

§License

This library is licensed under the BSD 3-Clause License.

Re-exports§

pub use darkbio_crypto as crypto;

Modules§

cloud: Cloud attestations, the rotating signing and encryption identities of the Dark Bio cloud.
device: Device attestations, the identities of Ark enclaves and of their emulated counterparts.
roots: Root keys of the Dark Bio ecosystem, embedded verbatim from the public keys of the Dark Bio transparency report repository. Only the environments enabled by the crate features embed their keys, the others have empty root sets. The fingerprints of every root are present in every build, so a signer can be named even when its key is not trusted.

Enums§

Environment: Environment represents the deployments of the ecosystem, which devices are built for and clouds run in, each with its own roots. Every environment can be named in every build, but its root keys are only embedded when the crate feature of the same name is enabled. An environment without keys has empty root sets, so nothing verifies under it.
Error: Failures during attestation verification.
Realm: Realm separates the hardware device universe from the emulated one. Hardware devices are attested once at manufacturing by the hardware roots and never expire, emulated devices are attested online by the emulator roots and always expire. The two realms never share trust.

Constants§

CLOUD_ATTESTATION_MAX_VALIDITY: Longest validity period a cloud attestation may carry.
CRYPTO_DOMAIN_CLOUD_ATTESTATION: Domain separator of cloud attestations, binding the signature of a cloud root to the attestation format so it cannot be replayed into other protocols using the same key.
CRYPTO_DOMAIN_DEVICE_ATTESTATION: Domain separator of device attestations, binding the signature of a root to the attestation format so it cannot be replayed into other protocols using the same key.
EMULATOR_ATTESTATION_MAX_VALIDITY: Longest validity period an emulator attestation may carry, bounding how long an emulated device stays attested.