---

name: password-based-authentication description: Security pattern for implementing password-based authentication. Use when designing login systems with username/password, implementing password storage, hashing, salting, peppering, password policies, or password reset flows. Specialization of the Authentication pattern.

Password-Based Authentication Security Pattern

A subject proves identity by providing a correct identifier (username/email) and corresponding password. Relies on the assumption that only the actual owner knows the correct password.

Core Components

Data Elements

• id: Identifier (username, email)
• pwd: Password provided by Subject
• hash(pwd): Hash value of password
• salt: Random value unique per Subject
• pepper: System-wide secret for additional protection

Password Hashing

Required Approach

1. Use modern password hashing algorithms: Argon2, scrypt, bcrypt, or PBKDF2
2. Never use general-purpose hash functions (MD5, SHA-1, SHA-256) alone
3. Always use salting (typically automatic with modern algorithms)

Salting

• Add random string unique per Subject before hashing
• Ensures identical passwords produce different hashes
• Salt stored in plaintext alongside hash
• Modern algorithms handle salt automatically

Peppering (Optional)

• System-wide secret added before hashing
• Stored separately from password store
• Provides additional protection if password store is compromised

Registration Flow

Three approaches for credential determination:

1. Subject provides identifier and password
2. Subject provides identifier; Registrar selects password
3. Registrar selects both identifier and password

Upon completion:

• Password Store contains: identifier, hash(salted password), salt
• Subject possesses: identifier and password

Password Policy

Enforce policies including:

• Minimum/maximum length
• Character requirements
• Common password blacklist
• Breach database checking

Password Reset

1. Verify Subject identity through out-of-band channel
2. Generate time-limited reset token
3. Never reveal whether account exists
4. Invalidate existing sessions after reset
5. Force re-authentication

Security Considerations

Password Store Protection

• Encrypt at rest
• Restrict access
• Monitor for breaches
• Detect tampering

Identifier Security

• Don't rely on identifier secrecy
• Prevent enumeration attacks
• Use consistent timing for valid/invalid identifiers

Verification Timing

• Use constant-time comparison
• Prevent timing attacks

Implementation Checklist

• Using Argon2/scrypt/bcrypt/PBKDF2
• Automatic salting enabled
• Password policy enforced
• Secure reset flow implemented
• Rate limiting on login attempts
• Constant-time hash comparison
• No credential logging

References

• Source: https://securitypatterns.distrinet-research.be/patterns/01_01_002__authentication_pwd/
• OWASP Password Storage Cheat Sheet