Crate crabka_security 

Security primitives used by Crabka brokers, clients, and tooling.

The crate owns the protocol-independent pieces of TLS, SASL, SCRAM, OAuth/OIDC, mTLS principal extraction, delegation-token HMACs, Kerberos exchange state, and principal modelling. Network I/O remains in the caller: OAuth introspection is represented by the async IntrospectionClient trait, and the broker/client crates provide concrete transports and wire the resulting validators into listener or connection handshakes.

SASL/PLAIN verification

use crabka_security::{AuthMethod, verify_plain};
use std::collections::HashMap;

let mut users = HashMap::new();
users.insert("alice".to_string(), "wonderland".to_string());

let principal = verify_plain(&users, "alice", b"wonderland").unwrap();
assert_eq!(principal.name, "alice");
assert_eq!(principal.auth_method, AuthMethod::SaslPlain);

Storing SCRAM credentials

use crabka_security::{SaslMechanism, hash_scram_password};

let credential = hash_scram_password(
    b"correct horse battery staple",
    SaslMechanism::ScramSha512,
    4096,
);
assert_eq!(credential.iterations, 4096);

Re-exports

pub use delegation_token::SecretBytes;

pub use delegation_token::compute_token_hmac;

pub use scram::ScramClientExchange;

pub use scram::ScramCredential;

pub use scram::ScramServerExchange;

pub use scram::StepResult;

pub use scram::derive_keys_from_salted;

pub use scram::hash_scram_password;

pub use scram::pbkdf2_salted;

pub use scram::scram_hash_len;

Modules

ca

Pure X.509 CA + leaf-cert generation for the operator’s clients-CA bootstrap. Reusable by inter-broker mTLS and cert hot-reload tests.

delegation_token

KIP-48 delegation token primitives — HMAC and secret-key wrapper that keeps the bytes out of Debug.

gssapi

SASL/GSSAPI (Kerberos) support. See SASL/GSSAPI Kerberos support.

scram

SCRAM (RFC 5802) — supports SHA-256 and SHA-512.

Structs

AuthOutcome

Outcome of an OAUTHBEARER validation: the authenticated principal plus the token’s expiry. The expiry populates SaslAuthenticateResponse.session_lifetime_ms and what the dispatch loop uses to schedule per-connection re-auth deadlines (KIP-368).

ClientInitialResponse

Parsed RFC 7628 client initial response.

DynamicServerConfig

Atomically swappable wrapper around a rustls::ServerConfig. Cheap to clone (one Arc bump); cheap to read (lock-free); the only expensive operation is reload_from, which re-parses cert files.

IntrospectionValidator

RFC 7662 opaque-token introspection validator. Calls the introspection endpoint per token (no caching — RFC 7662 §4 discourages caching without explicit lifetime info; SASL is once per connection so the cost is acceptable). Optionally calls OIDC userinfo after a successful introspection and merges the profile claims over the introspection claims.

Jwks

A parsed JWK key set. Lookups are by kid; keys without a kid are stored under the empty string and used when a token header omits kid and the set holds exactly one key.

JwksHandle

A cheaply-clonable, atomically-swappable holder for the live Jwks.

KafkaPrincipal

KIP-48: Kafka wire-level principal — the (principalType, name) pair carried in delegation-token records, ACL entries, and KafkaPrincipal-shaped fields across the Kafka protocol. Distinct from Principal which models the runtime session identity (auth method + OAuth groups). Format-stable: Display/FromStr round-trip the canonical Type:Name form.

Principal

SignedJwsValidator

Validates a signed JWS bearer token (RS256 / ES256) against a JWKS key set fetched from the identity provider, then checks the standard JWT claims and derives the connection principal.

TlsConfig

UnsecuredJwsValidator

Validates an unsecured JWS bearer token (alg: none) and derives the connection principal. Mirrors Kafka’s OAuthBearerUnsecuredValidatorCallbackHandler.

Enums

AuthError

AuthMethod

How a Principal was authenticated. A strict superset of SaslMechanism that also covers mTLS client-cert authentication and the implicit ANONYMOUS path on PLAINTEXT / SSL-no-mTLS listeners.

ClientAuthMode

Whether the server requests and verifies a client certificate during the TLS handshake (RFC 5246 §7.4.6 — Kafka’s mTLS path).

IntrospectionError

Transport-layer failures surfaced by IntrospectionClient. The validator maps these onto AuthError::IntrospectionTransport for the SASL handler.

JwksTrustError

ListenerProtocol

OAuthBearerValidator

The broker’s configured OAUTHBEARER token validator: the development-only unsecured-JWS path, production signed-JWT validation against a JWKS endpoint, or RFC 7662 opaque-token introspection. Defaults to unsecured.

SaslMechanism

TlsError

Traits

IntrospectionClient

HTTP transport contract for RFC 7662 introspection + OIDC userinfo. Lives in this crate to keep crates/security as the validator surface; the concrete reqwest-backed impl lives in crates/broker (oauth_introspection.rs) so this crate stays I/O-free.

Functions

build_client_config_from_pem

Read a PEM bundle of one or more CA certificates and produce a rustls::ClientConfig that trusts exactly those certificates. The returned config has no client auth (the broker does not present a client cert when fetching the JWKS endpoint).

extract_principal_from_cert

Parse cert_der and return the Subject DN in RFC 2253 format. Returns None if the bytes don’t parse as a valid X.509 cert.

invalid_token_json

The RFC 7628 server error response body for a rejected token. The JVM OAuthBearerSaslClient treats any non-empty first server message as an error and replies with a single \x01 kvsep, after which the broker completes the failure handshake.

parse_client_initial_response

Parse the SASL/OAUTHBEARER client initial response (RFC 7628 §3.1).

verify_plain

Verifies a SASL/PLAIN auth attempt against a static credential map.