uselesskey

Deterministic cryptographic test fixtures for Rust — stop committing PEM/DER blobs into your repos.

uselesskey is a test-fixture factory that generates cryptographic key material and X.509 certificates at runtime. It is not a crypto library — it replaces committed secret-shaped blobs with a single dev-dependency.

Do not use for production keys. Deterministic keys are predictable by design. Even random-mode keys are intended for tests only.

Why?

Secret scanners have changed the game for test fixtures:

This crate replaces "security policy + docs + exceptions" with one dev-dependency.

Feature Selection

The facade default feature set is empty. A bare dependency gives you core types like Factory, Mode, and Seed; enable only the fixture families you need.

Token-only consumers can stay lightweight:

[dev-dependencies]
uselesskey = { version = "0.4.0", default-features = false, features = ["token"] }

use uselesskey::{Factory, TokenFactoryExt, TokenSpec};

let fx = Factory::deterministic_from_str("api-key-fixtures");
let token = fx.token("svc-api", TokenSpec::api_key());

assert!(token.value().starts_with("uk_test_"));

Quick Start

If you want RSA fixtures, enable rsa explicitly:

[dev-dependencies]
uselesskey = { version = "0.4.0", features = ["rsa"] }

use uselesskey::{Factory, RsaFactoryExt, RsaSpec};

let fx = Factory::random();
let rsa = fx.rsa("my-service", RsaSpec::rs256());

let private_pem = rsa.private_key_pkcs8_pem();
let public_der = rsa.public_key_spki_der();

Deterministic Mode

Same seed + same label + same spec = identical output every time, regardless of call order:

use uselesskey::{Factory, RsaFactoryExt, RsaSpec};

let fx = Factory::deterministic_from_str("my-test-seed");
let rsa = fx.rsa("issuer", RsaSpec::rs256());

Or read the seed from an environment variable in CI:

use uselesskey::Factory;

let fx = Factory::deterministic_from_env("USELESSKEY_SEED")
    .unwrap_or_else(|_| Factory::random());

Supported Key Types

Feature Flags

The default feature set is empty.

Output Formats

Every key type provides:

• PKCS#8 PEM / DER — private keys
• SPKI PEM / DER — public keys
• Tempfiles — write_* methods for libraries that need file paths
• JWK / JWKS — with the jwk feature

X.509 certificates additionally provide PEM / DER cert output, identity PEM (cert + key), and chain PEM (leaf + intermediate).

Negative Fixtures

Test error-handling paths with intentionally broken material:

use uselesskey::{Factory, RsaFactoryExt, RsaSpec};
use uselesskey::negative::CorruptPem;

let fx = Factory::random();
let rsa = fx.rsa("test", RsaSpec::rs256());

let bad_pem   = rsa.private_key_pkcs8_pem_corrupt(CorruptPem::BadBase64);
let truncated = rsa.private_key_pkcs8_der_truncated(32);
let mismatch  = rsa.mismatched_public_key_spki_der();

X.509 chains support expired certs, hostname mismatch, unknown CA, and revoked leaf (with CRL):

use uselesskey::{Factory, X509FactoryExt, ChainSpec};

let fx = Factory::random();
let chain = fx.x509_chain("svc", ChainSpec::new("test.example.com"));

let expired    = chain.expired_leaf();
let wrong_host = chain.hostname_mismatch("wrong.example.com");
let unknown_ca = chain.unknown_ca();
let revoked    = chain.revoked_leaf();

Adapter Crates

Adapter crates bridge uselesskey fixtures to third-party library types. They are separate crates (not features) to avoid coupling versioning.

Microcrate Architecture

uselesskey is a facade crate that re-exports from a family of focused crates. If you only need one key type and want to minimize compile time, depend on the implementation crate directly:

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.