igbuend/password-based-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

| Role | Type | Responsibility | |------|------|----------------| | Subject | Entity | Provides identifier and password | | Enforcer | Enforcement Point | Ensures authentication before action processing | | Verification Manager | Entity | Collects inputs for password verification | | Comparator | Decision Point | Compares hash values | | Hasher | Cryptographic Primitive | Calculates hash values | | Password Store | Storage | Keeps hash values for registered identities | | Registrar | Entity | Handles subject registration | | Resetter | Entity | Handles credential reset | | Password Policy | Information Point | Rules passwords must satisfy | | SRNG | Cryptographic Primitive | Secure random number generator |

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