Rustango docs
← Authentifizierung

Passwörter

Ein Passwort zu speichern bedeutet, etwas zu speichern, das ein Angreifer selbst mit Ihrer gesamten Datenbank in der Hand nicht umkehren kann. Rustango liefert Ihnen das in zwei Aufrufen — hash beim Eingang, verify beim Ausgang — gestützt auf argon2id, den memory-hard Gewinner der Password Hashing Competition und die aktuelle Erstwahl der OWASP. Sie speichern, protokollieren oder vergleichen den Klartext niemals.

Passwörter in Rustango: hash() erzeugt eine gesalzene argon2id-PHC-Zeichenkette, verify() prüft einen Versuch dagegen, und verify_dummy() gleicht die Anmelde-Timing an

Quelle: rustango::passwords (hash, verify, verify_dummy, ihre _async-Formen, Argon2Params, needs_rehash, strength_score, StrengthIssue) — hinter dem Feature passwords (standardmäßig aktiviert). Für die in die Mandantenfähigkeit integrierten Passwort-Hilfsfunktionen siehe rustango::tenancy::password.

Ausführbare Version: jeder Ausschnitt unten ist aus dem getesteten Beispiel auth_demo kopiert — cargo test -p auth_demo --test auth_passwords.

Ein Begriff hier neu? hash, salt, argon2id, PHC-Zeichenkette — siehe das Glossar.

Dies ist die Vertiefung zum Abschnitt „Passwörter hashen und prüfen" des Sicherheitsleitfadens.


Inhaltsverzeichnis


Schnellstart

use rustango::passwords::{hash, verify};

// Signup — store the returned PHC string, never the plaintext.
let stored: String = hash("CorrectHorseBatteryStaple!42")?;

// Login — check an attempt against the stored hash.
if verify("CorrectHorseBatteryStaple!42", &stored)? {
    // credentials good
}

hash gibt eine PHC-Zeichenkette zurück — eine selbstbeschreibende Zeile, die den Algorithmus, seine Kostenparameter, das zufällige Salt und den Digest trägt:

$argon2id$v=19$m=19456,t=2,p=1$<base64 salt>$<base64 hash>

Da Salt und Parameter innerhalb der Zeichenkette mitreisen, benötigt verify nur den gespeicherten Wert und den Versuch — es gibt keine separate Salt-Spalte zu verwalten.


Warum argon2id

hash verwendet argon2id mit den von der OWASP empfohlenen Standardwerten (m=19 MiB, t=2, p=1). argon2id ist memory-hard: jeder Rateversuch kostet echten RAM, und genau das stumpft die GPU/ASIC-Farmen ab, die schnelle Hashes (MD5, SHA-256, sogar bcrypt bei niedrigen Kosten) per Brute-Force angreifbar machen. Zwei Eigenschaften sind für die Korrektheit wichtig:

  • Das Salting ist automatisch und pro Hash. Dasselbe Passwort zweimal zu hashen ergibt zwei verschiedene PHC-Zeichenketten, sodass identische Passwörter in Ihrer Tabelle nicht kollidieren und Angriffe mit vorberechneten Rainbow-Tables nicht greifen.

    let a = hash("same-password-12345")?;
    let b = hash("same-password-12345")?;
    assert_ne!(a, b);                 // different random salt each time
    assert!(verify("same-password-12345", &a)?);
    assert!(verify("same-password-12345", &b)?);
    
  • Die Prüfung erfolgt in konstanter Zeit beim Digest-Vergleich (argon2s eigener PasswordVerifier), sodass ein Byte-für-Byte-Timing-Leak nicht verraten kann, wie viel eines Versuchs richtig war.


Hashen bei der Registrierung

use rustango::passwords::{hash, strength_score};

fn create_user(username: &str, plaintext: &str) -> Result<String, String> {
    // Optional: nudge users away from weak choices (see below).
    let issues = strength_score(plaintext);
    if !issues.is_empty() {
        return Err(format!("password too weak: {issues:?}"));
    }
    // Store the PHC string on the user row (e.g. auth_users.password_hash).
    hash(plaintext).map_err(|e| e.to_string())
}

Prüfen bei der Anmeldung

use rustango::passwords::verify;

// `stored` is the PHC string you saved at signup.
let ok = verify(attempt, &stored)?;

verify gibt zurück:

  • Ok(true) — der Versuch stimmt überein.
  • Ok(false) — er stimmt nicht.
  • Err(PasswordError::Verify) — stored war keine gültige PHC-Zeichenkette (eine beschädigte oder abgeschnittene Spalte), behandeln Sie es also als fehlgeschlagene Anmeldung, nicht als 500.

Ein vollständiger Login-Handler

Das ist der login-Handler aus Erste Schritte, Schritt 14, kompiliert und getestet im Beispiel getting_started_blog. Er bremst Fehlversuche mit login_throttle, ruft für einen unbekannten Benutzer verify_dummy_async auf, antwortet für einen unbekannten Benutzer und ein falsches Passwort mit demselben 401 und gibt ein JWT für 15 Minuten zurück. Die kleinen Helfer, die er aufruft (normalize, server_error, bad_credentials, jwt_secret), und die Typen ApiUser, Credentials und TokenResponse stehen dort in derselben Datei.

use axum::extract::State;
use axum::response::{IntoResponse, Response};
use axum::Json;
use rustango::jwt::{self, Claims};
use rustango::login_throttle::{self, ClientIp, LoginRefused, LoginScope};
use rustango::passwords::{self, PasswordError};
use rustango::prelude::*;
use rustango::sql::Pool;

/// `POST /api/login` — check the password and hand out a short-lived token.
pub async fn login(
    State(pool): State<Pool>,
    ip: ClientIp,
    Json(body): Json<Credentials>,
) -> Result<Json<TokenResponse>, Response> {
    // First: with no valid key every login is a 500, right password or not.
    let secret = jwt_secret().map_err(IntoResponse::into_response)?;
    let username = normalize(&body.username);

    // Before any lookup: 429 once this IP (or everyone) failed too often.
    // `Sso(name)`: its own total limit, a per-IP limit shared with SSO sign-ins, no account lock.
    let scope = LoginScope::Sso("blog-api".to_owned());
    let attempt = login_throttle::shared()
        .begin(&scope, &ip, &username)
        .await
        .map_err(IntoResponse::into_response)?;

    let found = ApiUser::objects()
        .where_(ApiUser::username.eq(username))
        .first(&pool)
        .await
        .map_err(|e| server_error(e).into_response())?;

    let Some(user) = found else {
        // Do the same slow work as a real check, so timing does not reveal the name is unknown.
        if passwords::verify_dummy_async(&body.password).await.is_err() {
            return Err(LoginRefused::Busy.into_response()); // 503: no hashing slot free
        }
        attempt.failed().await;
        return Err(bad_credentials().into_response());
    };
    let password_ok = match passwords::verify_async(&body.password, &user.password_hash).await {
        Ok(ok) => ok,
        Err(PasswordError::Busy) => return Err(LoginRefused::Busy.into_response()),
        // A corrupt stored hash counts as a wrong password, not a server error.
        Err(_) => false,
    };
    if !password_ok {
        attempt.failed().await;
        return Err(bad_credentials().into_response());
    }
    attempt.succeeded().await;

    let id = user.id.get().copied().unwrap_or_default();
    let claims = Claims::new(id.to_string()).ttl(TOKEN_TTL); // subject = user id
    let access_token =
        jwt::encode(&claims, &secret).map_err(|e| server_error(e).into_response())?;
    Ok(Json(TokenResponse {
        access_token,
        token_type: "Bearer",
        expires_in: TOKEN_TTL.as_secs(),
    }))
}

Timing-sichere Anmeldungen (Kontoaufzählung)

Wenn Ihre Anmeldung das teure verify nur ausführt, wenn der Benutzername existiert, kehrt ein unbekannter Benutzername merklich schneller zurück als ein echter — und diese Zeitlücke lässt einen Angreifer gültige Konten aufzählen. verify_dummy schließt sie: rufen Sie es im Zweig Benutzer-nicht-gefunden (und Konto-inaktiv) auf, damit jede Anmeldung unabhängig davon die Arbeit eines argon2-verify aufwendet.

use rustango::passwords::{verify, verify_dummy};

let row = users::find_by_username(username).await?;
let authenticated = match row {
    Some(u) if u.is_active => verify(attempt, &u.password_hash)?,
    _ => {
        verify_dummy(attempt); // burn the same work, then fail
        false
    }
};

Stärkeprüfungen

strength_score gibt einen Vec<StrengthIssue> zurück — leer bedeutet „gut genug". Es ist eine bewusst leichtgewichtige Heuristik, um Benutzer zu ermutigen, kein hartes Richtlinien-Gatter; kombinieren Sie sie für ernsthafte Deployments mit einer Prüfung gegen eine Leak-Liste (HIBP / pwned-passwords).

use rustango::passwords::{strength_score, StrengthIssue};

assert!(strength_score("Tr0ub4dor&3-CorrectBattery").is_empty());
assert!(strength_score("password123").contains(&StrengthIssue::KnownWeak));
assert!(strength_score("short").contains(&StrengthIssue::TooShort));
StrengthIssueAusgelöst, wenn
TooShortweniger als 12 Zeichen
NoDigitsOrSymbolsnur Buchstaben — keine Ziffer oder kein Symbol
NoVarietynur Kleinbuchstaben
KnownWeakstimmt mit der kleinen eingebauten Liste schwacher Passwörter überein (ohne Berücksichtigung der Groß-/Kleinschreibung)

Wo der Hash lebt

Die PHC-Zeichenkette ist lediglich eine String-Spalte auf dem beliebigen Kontomodell, das Ihnen gehört. Im Beispiel auth_demo:

#[derive(Model, Clone, Debug)]
#[rustango(table = "auth_users", display = "username")]
pub struct User {
    #[rustango(primary_key)]
    pub id: Auto<i64>,
    #[rustango(max_length = 150, unique)]
    pub username: String,
    #[rustango(max_length = 254)]
    pub email: String,
    #[rustango(max_length = 255)]      // PHC strings are ~95 chars at these params
    pub password_hash: String,
    pub is_active: bool,
    pub is_superuser: bool,
}

Sobald der Benutzer authentifiziert ist, übergeben Sie an eine Session (für Browser-Anwendungen) oder stellen Sie ein JWT aus (für APIs).


Async-Code

hash, verify und verify_dummy blockieren: ein argon2-Aufruf belegt einen Runtime-Worker für den ganzen Hash. Rufen Sie in einem Handler stattdessen hash_async, verify_async und verify_dummy_async auf. Sie laufen im Blocking-Pool, höchstens ein Job pro CPU gleichzeitig.

Ein Job wartet bis zu hash_wait() auf einen freien Platz (Standard 5 s, DEFAULT_HASH_WAIT) und schlägt dann mit PasswordError::Busy fehl. Antworten Sie darauf mit einem 503, gleich für einen bekannten und einen unbekannten Benutzer. Setzen Sie die Wartezeit mit [auth] hash_wait_ms oder beim Start mit configure_hash_wait(duration). Die [auth]-Schlüssel wendet manage::Cli beim Laden der Einstellungen an; eine App, die server::Builder ohne ihn baut, ruft stattdessen die Funktionen auf.


Kosten und Neu-Hashen

Neue Hashes nutzen argon2_params(), standardmäßig Argon2Params::DEFAULT (m=19456 KiB, t=2, p=1). Erhöhen Sie sie mit [auth] argon2_memory_kib, argon2_iterations und argon2_parallelism, oder rufen Sie beim Start configure_argon2(Argon2Params::new(m, t, p)?) auf; ein im Code gesetzter Wert gewinnt gegen die Einstellungen, und die Schlüssel wirken nur über manage::Cli. Argon2Params::new lehnt eine Kombination ab, die argon2 ablehnt.

Alte Hashes verifizieren weiterhin, denn ihre Kosten stehen in der PHC-Zeichenkette. needs_rehash(&stored) ist true, wenn ein Hash schwächer ist als die heutigen Kosten (oder nicht argon2id v19). Nach einer erfolgreichen Anmeldung:

  • rehash_async(attempt, &stored) liefert einen frischen Hash, wenn einer fällig ist, sonst None.
  • upgrade_stored_hash(&pool, Model::SCHEMA, id, attempt, &stored) speichert ihn auch in der Spalte password_hash der Zeile, aber nur wenn diese Spalte noch stored enthält, und liefert den jetzt gültigen Hash.

Hinweise und Grenzen

  • Niemals den Klartext speichern, protokollieren oder mit == vergleichen. hash → speichern; verify → prüfen. Das ist der ganze Vertrag.
  • Die Kostenparameter stehen standardmäßig auf der OWASP-Untergrenze. Sie später anzuheben ist sicher — alte Hashes verifizieren weiterhin (ihre Parameter leben in der PHC-Zeichenkette), und upgrade_stored_hash hasht bei der nächsten erfolgreichen Anmeldung neu.
  • strength_score ist eine Heuristik, keine Richtlinien-Engine — es wird Summer2024! nicht erkennen. Legen Sie für echte Stärkedurchsetzung eine Leak-Listen-Abfrage darüber.
  • Für mandantenfähige Anwendungen mit dem Benutzerspeicher des Frameworks bevorzugen Sie rustango::tenancy::password (dasselbe argon2id, integriert in das Benutzermodell des Mandanten). Dieses Modul ist die eigenständige Version für Anwendungen, die ihre eigene User-Tabelle besitzen.

Siehe auch