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.
Quelle:
rustango::passwords(hash,verify,verify_dummy, ihre_async-Formen,Argon2Params,needs_rehash,strength_score,StrengthIssue) — hinter dem Featurepasswords(standardmäßig aktiviert). Für die in die Mandantenfähigkeit integrierten Passwort-Hilfsfunktionen sieherustango::tenancy::password.Ausführbare Version: jeder Ausschnitt unten ist aus dem getesteten Beispiel
auth_demokopiert —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 · Warum argon2id
- Hashen bei der Registrierung · Prüfen bei der Anmeldung
- Timing-sichere Anmeldungen · Stärkeprüfungen
- Wo der Hash lebt · Async-Code · Kosten und Neu-Hashen
- Hinweise und Grenzen
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)—storedwar 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));
StrengthIssue | Ausgelöst, wenn |
|---|---|
TooShort | weniger als 12 Zeichen |
NoDigitsOrSymbols | nur Buchstaben — keine Ziffer oder kein Symbol |
NoVariety | nur Kleinbuchstaben |
KnownWeak | stimmt 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, sonstNone.upgrade_stored_hash(&pool, Model::SCHEMA, id, attempt, &stored)speichert ihn auch in der Spaltepassword_hashder Zeile, aber nur wenn diese Spalte nochstoredenthä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_hashhasht bei der nächsten erfolgreichen Anmeldung neu. strength_scoreist eine Heuristik, keine Richtlinien-Engine — es wirdSummer2024!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.
