Auth

Standards

Architecture

Protocol (FTP / SMTP / HTTP auth factory)
        │
        ├── TrustPolicy::evaluate(IdentityMaterial, PeerContext)
        │         → Accept | Reject
        │
        └── SASL: create_server / create_client
                  ↔ CredentialStore (passwords, HA1, SCRAM, tokens, certs)

PasswordTrustPolicy is a small demo policy; production apps implement TrustPolicy or back SASL with a real CredentialStore.

TrustPolicy

use hopf_auth::{IdentityMaterial, PeerContext, TrustDecision, TrustPolicy};

fn evaluate(&self, id: &IdentityMaterial, peer: &PeerContext) -> TrustDecision {
    // …
}

FTP stock handler and SMTP AUTH PLAIN call this layer. See FTP, SMTP.

Credential stores

CredentialStore overridable methods: password_match, plaintext_password, digest_ha1, cram_md5_digest, scram_credentials, validate_bearer, authenticate_certificate, authorize_as, supported_mechanisms.

use hopf_auth::PasswordStore;

let store = PasswordStore::new()
    .with_user("alice", "secret")
    .with_token("tok", "alice")
    .with_certificate("cn=alice", "alice")
    .shared();

SCRAM iterations default 4096 (ScramCredentials::derive(password, salt, iterations)).

SASL mechanisms

pub enum SaslMechanism {
    Plain,
    Login,
    CramMd5,
    DigestMd5,
    ScramSha256,
    OauthBearer,
    External,
}

Helpers on the enum: name, from_name, is_challenge_response, requires_tls, all.

use hopf_auth::{create_server, create_client, SaslMechanism, SaslServerOptions};

let mut server = create_server(
    SaslMechanism::ScramSha256,
    store,
    SaslServerOptions {
        hostname: "localhost".into(),
        realm: "hopf".into(),
        peer_certificate: None,
        channel_binding: None,
    },
);
let mut client = create_client(SaslMechanism::ScramSha256, "alice", "secret", "localhost", None);

// Alternate challenge/response via server.step / client.evaluate

Symmetric client + server exchanges for all seven Gumdrop-parity mechanisms, plus SCRAM-SHA-256-PLUS. requires_tls guides operators (e.g. PLAIN should be under TLS).

SCRAM channel binding

ScramSha256Client::new_plus(username, password, channel_binding) / ScramSha256Server::with_channel_binding(channel_binding) add real tls-server-end-point (RFC 5929 section 4) channel binding: the caller supplies this connection's channel-binding bytes (a hash of the server's TLS certificate — hopf-auth has no TLS awareness of its own, the same pattern ExternalServer::with_peer_certificate already uses). The server independently recomputes the expected c= value from the GS2 header the client actually sent plus its own channel-binding data and rejects a mismatch — the property that defeats a MITM relaying the SASL exchange across two different TLS connections. Not implemented: cross-mechanism downgrade detection (noticing a MITM stripped PLUS from the advertised mechanism list) — that needs the session/capability-advertisement layer, not this mechanism module.

HTTP Digest helpers

Module http_digest: challenge_header, new_nonce, verify_authorization, client_authorization. verify_authorization takes an expected_nonce: Option<&str> — real replay protection requires the caller to track issued nonces and pass the specific one being redeemed (single-use, with expiry), which hopf-http's DigestAuthFactory/DigestAuthHandler now does: each challenge nonce is tracked in a map, consumed (removed) on first use, and pruned after DigestAuthConfig::nonce_ttl (default 5 minutes, overridable via with_nonce_ttl) if never used — so a captured, cryptographically-valid Authorization: Digest header can't be replayed, even verbatim.

HTTP Basic / Digest / Bearer request wrappers are in hopf-http (BasicAuthFactory, DigestAuthFactory, BearerAuthFactory) and call into trust / digest helpers — see HTTP server.

OAuth 2.0 token introspection

Module oauth_introspection implements RFC 7662 for real, replacing the local static token map PasswordStore::validate_bearer uses by default:

• IntrospectionRequest::to_form_body() — the application/x-www-form-urlencoded token + token_type_hint body per section 2.1.
• IntrospectionResponse::parse(json) — reads active / username / scope / exp from a section 2.2 response via a small purpose-built JSON reader (no JSON crate dependency); unknown/nested fields (aud, iss, client_id, ...) are structurally skipped, not rejected.
• IntrospectionTransport — the caller supplies the actual HTTP POST (hopf-auth has no network I/O of its own; hopf-http, which does, already depends on hopf-auth, so the dependency can't run the other way). Wire it to hopf-http's client, run off the reactor thread the same way other blocking work in this workspace is.
• IntrospectionCredentialStore::new(inner, transport) — a CredentialStore that delegates every method to inner except validate_bearer, which calls the introspection endpoint and requires active: true (plus a local exp check as defence in depth against a stale cached response, even though the RFC doesn't require it).

Configuration

SaslServerOptions

PasswordStore

Enrollment accepts a password once, then stores only SCRAM-SHA-256 material (and HA1 when a digest realm is set). plaintext_password always returns None — CRAM-MD5 and POP3 APOP are not supported by this store. password_match re-derives StoredKey and compares in constant time.

No Cargo features for the demo store.

PamCredentialStore

Optional feature pam on hopf-auth (and umbrella hopf feature pam). Unix only; links libpam / OpenPAM via in-tree FFI.

// Cargo.toml: hopf-auth = { version = "…", features = ["pam"] }
use hopf_auth::{PamCredentialStore, PamStoreConfig};

let store = PamCredentialStore::new(PamStoreConfig::new("login"))
    .shared();
// SmtpConfig::new(…).with_store(store)

• Mechanisms: PLAIN, LOGIN only (no digest/SCRAM/bearer).
• password_match is blocking — call from a storage/worker pool, never a reactor thread.
• Default service name: login (DEFAULT_PAM_SERVICE). Point at a custom PAM stack (e.g. /etc/pam.d/hopf) when deploying.

Wiring

FTP:

let policy = PasswordTrustPolicy::default().with_user("ftp", "ftp").shared();
FtpConfig::new(addr, root, policy);

SMTP (full SASL mechanism set via CredentialStore, same as POP3/IMAP below):

SmtpConfig::new(addr, hostname)
    .with_tls(acceptor)
    .with_store(store)
    .auth_required(true);

HTTP (in hopf-http): wrap a ServerHandlerFactory with BasicAuthFactory / DigestAuthFactory / BearerAuthFactory using a TrustPolicy or realm config (BasicAuthConfig { realm }, DigestAuthConfig { realm }).

Examples

No dedicated examples/auth crate. Consumed by:

• Cookbook: FTP — FTP_USER / FTP_PASS
• Cookbook: SMTP
• examples/smtp-ldap — LdapCredentialStore + SmtpConfig::with_store
• HTTP hello examples with auth factories when configured

Limitations

• GSSAPI / Kerberos (RFC 4752) — not implemented today; planned as an optional gssapi feature with KDC/keytab work on StorageExecutor (Gumdrop parity). Would also unlock RFC 1961 GSSAPI auth for SOCKS.
• DIGEST-MD5 kept for parity only (deprecated by RFC 6331).
• OAUTHBEARER and XOAUTH2 carry the token in the client “password” slot.
• PasswordStore is in-memory (demo-grade): enrolls from a password then keeps SCRAM (+ optional Digest HA1) only. For production password AUTH, use LdapCredentialStore or feature pam’s PamCredentialStore.
• CRAM-MD5 and POP3 APOP need a recoverable secret (or a custom cram_md5_digest / APOP verifier) — not provided by PasswordStore.
• SMTP wire currently advertises AUTH PLAIN only (SMTP), even though the auth crate supports more mechanisms.
• SCRAM-SHA-256-PLUS has no cross-mechanism downgrade detection — see the channel binding section.
• No protocol crate in this workspace wires real tls-server-end-point channel-binding data through to create_server yet, which is why ScramSha256Plus is excluded from SaslMechanism::all() (and so isn't advertised by any store's default supported_mechanisms()) even though the mechanism itself is fully implemented and tested.
• IntrospectionCredentialStore (RFC 7662) needs a caller-supplied IntrospectionTransport for the actual HTTP call — hopf-auth has no network I/O of its own, so nothing in this workspace wires one up by default; PasswordStore::validate_bearer (the default) is still a local static token map.

GitHub