Crate uselesskey

Expand description

uselesskey generates runtime key fixtures for tests.

The point is operational, not cryptographic: keep secrets-shaped blobs out of your git history while still testing against “real-shaped” inputs (PKCS#8 PEM/DER, SPKI, etc.).

Not for production. Deterministic keys are predictable by design.

For integration with third-party crypto crates, see the adapter crates: uselesskey-jsonwebtoken, uselesskey-rustls, uselesskey-tonic, uselesskey-ring, uselesskey-rustcrypto, and uselesskey-aws-lc-rs.

§Quick Start

Create a factory and generate RSA key fixtures:

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

// Random mode: each run produces different keys (still cached per-process)
let fx = Factory::random();
let keypair = fx.rsa("my-service", RsaSpec::rs256());

// Access keys in various formats
let pem = keypair.private_key_pkcs8_pem();
let der = keypair.private_key_pkcs8_der();
let pub_pem = keypair.public_key_spki_pem();

assert!(pem.contains("-----BEGIN PRIVATE KEY-----"));
assert!(!der.is_empty());

§Deterministic Mode

For reproducible test fixtures, use deterministic mode with a seed:

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

// Create a deterministic factory with a fixed seed
let seed = Seed::from_env_value("test-seed").unwrap();
let fx = Factory::deterministic(seed);

// Same seed + same label + same spec = same key, regardless of call order
let key1 = fx.rsa("issuer", RsaSpec::rs256());
let key2 = fx.rsa("issuer", RsaSpec::rs256());

assert_eq!(key1.private_key_pkcs8_pem(), key2.private_key_pkcs8_pem());

§Environment-Based Seeds

In CI, you often want to read the seed from an environment variable:

use uselesskey::Factory;

// This reads from the environment variable and parses the seed
// Returns Err if the variable is not set
let fx = Factory::deterministic_from_env("USELESSKEY_SEED").unwrap();

§Negative Fixtures

Test error handling with intentionally corrupted keys:

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

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

// Get a PEM with a corrupted header
let bad_pem = keypair.private_key_pkcs8_pem_corrupt(CorruptPem::BadHeader);
assert!(bad_pem.contains("-----BEGIN CORRUPTED KEY-----"));

// Get truncated DER bytes
let truncated = keypair.private_key_pkcs8_der_truncated(10);
assert_eq!(truncated.len(), 10);

// Get a mismatched public key (valid but doesn't match the private key)
let mismatched = keypair.mismatched_public_key_spki_der();
assert!(!mismatched.is_empty());

§Temporary Files

Some libraries require file paths. Use write_* methods which return TempArtifact:

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

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

// Write to a tempfile (auto-cleaned on drop)
let temp: TempArtifact = keypair.write_private_key_pkcs8_pem().unwrap();
let path = temp.path();

assert!(path.exists());
// Pass `path` to libraries that need file paths

§JWK Support

With the jwk feature, generate JSON Web Keys:

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

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

// Get a stable key ID
let kid = keypair.kid();

// Get the public JWK
let jwk = keypair.public_jwk();
let jwk_value = jwk.to_value();
assert_eq!(jwk_value["kty"], "RSA");
assert_eq!(jwk_value["alg"], "RS256");

// Get a JWKS containing one key
let jwks = keypair.public_jwks();
let jwks_value = jwks.to_value();
assert!(jwks_value["keys"].is_array());

§X.509 Certificates

With the x509 feature, generate self-signed certificates and certificate chains:

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

let fx = Factory::random();
let cert = fx.x509_self_signed("my-service", X509Spec::self_signed("localhost"));

assert!(cert.cert_pem().contains("BEGIN CERTIFICATE"));
assert!(!cert.cert_der().is_empty());
assert!(!cert.private_key_pkcs8_der().is_empty());

§Features

Feature	Description
`rsa`	RSA key fixtures (default)
`ecdsa`	ECDSA P-256/P-384 key fixtures
`ed25519`	Ed25519 key fixtures
`hmac`	HMAC secret fixtures
`token`	API key/bearer token fixtures
`pgp`	OpenPGP key fixtures
`x509`	X.509 certificate and chain fixtures
`jwk`	JWK/JWKS output for all key types
`all-keys`	All key types (rsa + ecdsa + ed25519 + hmac + pgp)
`full`	Everything: all-keys + token + x509 + jwk

Modules§

jwk: JWK/JWKS types and builder.
negative: Generic negative-fixture helpers (corrupt PEM, truncate DER, etc.).
prelude: Common imports for tests.

Structs§

ArtifactId: Identifier used for deterministic artifact cache entries.
ChainSpec: Specification for generating a three-level X.509 certificate chain (root CA -> intermediate CA -> leaf).
DerivationVersion: Version tag for the derivation scheme.
EcdsaKeyPair: An ECDSA keypair fixture with various output formats.
Ed25519KeyPair: An Ed25519 keypair fixture with various output formats.
Ed25519Spec: Specification for Ed25519 key generation.
Factory: How a Factory generates artifacts.
HmacSecret: An HMAC secret fixture.
KeyUsage: Key usage flags for X.509 certificates.
PgpKeyPair
RsaKeyPair: An RSA keypair fixture with various output formats.
RsaSpec: Specification for RSA key generation.
Seed: Seed bytes derived from user input for deterministic fixtures.
TempArtifact
TokenFixture: A token fixture with a generated value.
X509Cert: An X.509 certificate fixture.
X509Chain: A three-level X.509 certificate chain (root CA → intermediate CA → leaf).
X509Spec: Specification for generating an X.509 certificate.

Enums§

ChainNegative: Types of invalid certificate chains for negative testing.
EcdsaSpec: ECDSA algorithm specification.
Error: Errors for uselesskey-core.
HmacSpec: Specification for HMAC secret generation.
Mode: How a Factory generates artifacts.
NotBeforeOffset: Offset for the not_before field.
PgpSpec: Specification for OpenPGP fixture generation.
TokenSpec: Specification for token fixture generation.
X509Negative: Types of invalid X.509 certificates for negative testing.

Constants§

DOMAIN_ECDSA_KEYPAIR: Cache domain for ECDSA keypair fixtures.
DOMAIN_ED25519_KEYPAIR: Cache domain for Ed25519 keypair fixtures.
DOMAIN_HMAC_SECRET: Cache domain for HMAC secret fixtures.
DOMAIN_PGP_KEYPAIR: Cache domain for OpenPGP keypair fixtures.
DOMAIN_RSA_KEYPAIR: Cache domain for RSA keypair fixtures.
DOMAIN_TOKEN_FIXTURE: Cache domain for token fixtures.
DOMAIN_X509_CERT: Cache domain for X.509 certificate fixtures.
DOMAIN_X509_CHAIN: Cache domain for X.509 certificate chain fixtures.

Traits§

EcdsaFactoryExt: Extension trait to hang ECDSA helpers off the core Factory.
Ed25519FactoryExt: Extension trait to hang Ed25519 helpers off the core Factory.
HmacFactoryExt: Extension trait to hang HMAC helpers off the core Factory.
PgpFactoryExt: Extension trait to hang OpenPGP helpers off the core Factory.
RsaFactoryExt: Extension trait to hang RSA helpers off the core Factory.
TokenFactoryExt: Extension trait to hang token helpers off the core Factory.
X509FactoryExt: Extension trait to add X.509 certificate generation to Factory.

Type Aliases§

ArtifactDomain: Domain strings are used to separate unrelated fixture types.