Struct Authenticator 

pub struct Authenticator { /* private fields */ }

Negotiates a challenge once, then answers every subsequent request in the session (RFC 7235 WWW-Authenticate/Authorization; RFC 2326 §14 for RTSP; RFC 6750 for Bearer).

Construct with Authenticator::from_challenge on the first 401/407, then call Authenticator::authorization for every outgoing request — including the immediate retry. Call from_challenge again if the server re-challenges with a fresh nonce (stale=true) to pick it up.

Implementations

impl Authenticator

pub fn from_challenge( www_authenticate: &str, credentials: Credentials, ) -> Result<Self>

Builds an authenticator from a WWW-Authenticate challenge value and the caller’s credentials.

For Credentials::Basic/Digest, the challenge is parsed by http_auth, which itself decides the wire scheme (Basic or Digest) from the challenge content — not from which Credentials variant was passed in. For Credentials::Bearer, the challenge value is not inspected: RFC 6750 needs no challenge round-trip, so the token is used as-is.

Examples found in repository

examples/client_respond.rs (line 36)

fn main() {
    // --- Basic (RFC 7617): a one-shot respond(), no session state needed.
    let value = respond(
        "Basic realm=\"cameras\"",
        &RequestContext::new("GET", "/stream/media.m3u8"),
        Credentials::new("admin", "hunter2"),
    )
    .expect("Basic responds to any challenge shape");
    println!("[basic]  Authorization: {value}");
    assert!(value.starts_with("Basic "));

    // --- Digest (RFC 7616): parses the server's nonce/realm/qop out of the
    // challenge, then computes HA1/HA2/response. Demonstrated with an
    // Authenticator (not the one-shot respond()) since a real session reuses
    // it across requests so the nonce count (`nc`) advances correctly.
    let digest_challenge = "Digest realm=\"cameras\", \
        nonce=\"dcd98b7102dd2f0e8b11d0f600bfb0c093\", qop=\"auth\", algorithm=MD5";
    let mut auth =
        Authenticator::from_challenge(digest_challenge, Credentials::new("admin", "hunter2"))
            .expect("challenge parses");
    let value = auth
        .authorization(&RequestContext::new(
            "DESCRIBE",
            "rtsp://camera.example.com/live",
        ))
        .expect("computes a Digest Authorization value");
    println!("[digest] Authorization: {value}");
    assert!(value.starts_with("Digest "));

    // A second request on the same Authenticator advances `nc` — the
    // computed value differs even though nothing else about the request
    // changed (RFC 7616 §3.3 requires a fresh `nc` per request).
    let second = auth
        .authorization(&RequestContext::new(
            "DESCRIBE",
            "rtsp://camera.example.com/live",
        ))
        .expect("computes a second Digest Authorization value");
    assert_ne!(value, second, "nc must advance across requests");
    println!("[digest] Authorization (2nd request, nc advanced): {second}");

    // --- Bearer (RFC 6750): no challenge round-trip needed at all — the
    // challenge value is ignored, the token is sent verbatim.
    let value = respond(
        "ignored — Bearer needs no challenge round-trip",
        &RequestContext::new("GET", "/stream/media.m3u8"),
        Credentials::bearer("mytoken123"),
    )
    .expect("Bearer always responds");
    println!("[bearer] Authorization: {value}");
    assert_eq!(value, "Bearer mytoken123");
}

pub fn authorization(&mut self, ctx: &RequestContext<'_>) -> Result<String>

Computes the Authorization header value for ctx.

For Basic/Digest this advances the Digest nonce count on every call (RFC 7616 §3.3); for Bearer it always returns Bearer <token> (RFC 6750).

Examples found in repository

examples/client_respond.rs (lines 39-42)

fn main() {
    // --- Basic (RFC 7617): a one-shot respond(), no session state needed.
    let value = respond(
        "Basic realm=\"cameras\"",
        &RequestContext::new("GET", "/stream/media.m3u8"),
        Credentials::new("admin", "hunter2"),
    )
    .expect("Basic responds to any challenge shape");
    println!("[basic]  Authorization: {value}");
    assert!(value.starts_with("Basic "));

    // --- Digest (RFC 7616): parses the server's nonce/realm/qop out of the
    // challenge, then computes HA1/HA2/response. Demonstrated with an
    // Authenticator (not the one-shot respond()) since a real session reuses
    // it across requests so the nonce count (`nc`) advances correctly.
    let digest_challenge = "Digest realm=\"cameras\", \
        nonce=\"dcd98b7102dd2f0e8b11d0f600bfb0c093\", qop=\"auth\", algorithm=MD5";
    let mut auth =
        Authenticator::from_challenge(digest_challenge, Credentials::new("admin", "hunter2"))
            .expect("challenge parses");
    let value = auth
        .authorization(&RequestContext::new(
            "DESCRIBE",
            "rtsp://camera.example.com/live",
        ))
        .expect("computes a Digest Authorization value");
    println!("[digest] Authorization: {value}");
    assert!(value.starts_with("Digest "));

    // A second request on the same Authenticator advances `nc` — the
    // computed value differs even though nothing else about the request
    // changed (RFC 7616 §3.3 requires a fresh `nc` per request).
    let second = auth
        .authorization(&RequestContext::new(
            "DESCRIBE",
            "rtsp://camera.example.com/live",
        ))
        .expect("computes a second Digest Authorization value");
    assert_ne!(value, second, "nc must advance across requests");
    println!("[digest] Authorization (2nd request, nc advanced): {second}");

    // --- Bearer (RFC 6750): no challenge round-trip needed at all — the
    // challenge value is ignored, the token is sent verbatim.
    let value = respond(
        "ignored — Bearer needs no challenge round-trip",
        &RequestContext::new("GET", "/stream/media.m3u8"),
        Credentials::bearer("mytoken123"),
    )
    .expect("Bearer always responds");
    println!("[bearer] Authorization: {value}");
    assert_eq!(value, "Bearer mytoken123");
}

Trait Implementations

impl Debug for Authenticator

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.