How to Authentication Password Manager: Expert Tips

# password_hashing.py\n# Requires: pynacl >= 1.5.0 (libsodium 1.0.18+), Python 3.12+\nimport hashlib\nimport os\nimport time\nfrom typing import Tuple, Optional\nfrom nacl.exceptions import BadSignatureError, ValueError as NaClValueError\nfrom nacl.pwhash import argon2id\n\nclass PasswordHasher:\n    """Production-grade Argon2id password hasher compliant with NIST SP 800-63B."""\n    \n    # NIST-recommended parameters for 2024: 128MB memory, 3 iterations, 4 parallelism lanes\n    DEFAULT_MEM_LIMIT = 128 * 1024 * 1024  # 128MB\n    DEFAULT_ITERATIONS = 3\n    DEFAULT_PARALLELISM = 4\n    DEFAULT_HASH_LEN = 32  # 256-bit hash\n    DEFAULT_SALT_LEN = 16  # 128-bit salt\n\n    def __init__(self, mem_limit: int = DEFAULT_MEM_LIMIT, iterations: int = DEFAULT_ITERATIONS,\n                 parallelism: int = DEFAULT_PARALLELISM, hash_len: int = DEFAULT_HASH_LEN,\n                 salt_len: int = DEFAULT_SALT_LEN):\n        """Initialize hasher with tunable cost parameters.\n        \n        Args:\n            mem_limit: Memory usage in bytes (minimum 64MB for production)\n            iterations: Number of iterations (minimum 3 per NIST)\n            parallelism: Number of parallel lanes (matches CPU cores if possible)\n            hash_len: Length of derived hash in bytes\n            salt_len: Length of random salt in bytes\n        """\n        if mem_limit < 64 * 1024 * 1024:\n            raise ValueError(f"mem_limit must be at least 64MB, got {mem_limit} bytes")\n        if iterations < 3:\n            raise ValueError(f"iterations must be at least 3, got {iterations}")\n        self.mem_limit = mem_limit\n        self.iterations = iterations\n        self.parallelism = parallelism\n        self.hash_len = hash_len\n        self.salt_len = salt_len\n\n    def hash_password(self, plain_password: str) -> Tuple[str, str]:\n        """Hash a plaintext password with Argon2id, return (salt_hex, hash_hex).\n        \n        Args:\n            plain_password: User's plaintext password (must be non-empty)\n        \n        Returns:\n            Tuple of hex-encoded salt and hex-encoded derived hash\n        \n        Raises:\n            ValueError: If plain_password is empty or too long (>128 chars)\n            OSError: If system entropy source is unavailable\n        """\n        if not plain_password:\n            raise ValueError("plain_password cannot be empty")\n        if len(plain_password) > 128:\n            raise ValueError("plain_password cannot exceed 128 characters")\n        \n        # Generate cryptographically secure random salt\n        try:\n            salt = os.urandom(self.salt_len)\n        except OSError as e:\n            raise OSError(f"Failed to generate random salt: {e}") from e\n        \n        # Encode password to bytes (UTF-8, no BOM)\n        password_bytes = plain_password.encode("utf-8")\n        \n        # Derive hash using Argon2id with configured parameters\n        try:\n            # kdf method: salt, password, size, opslimit (iterations), memlimit (bytes)\n            derived_hash = argon2id.kdf(\n                self.hash_len,\n                password_bytes,\n                salt,\n                self.iterations,\n                self.mem_limit\n            )\n        except NaClValueError as e:\n            raise ValueError(f"Argon2id KDF failed: {e}") from e\n        \n        # Return hex-encoded values for storage (safe for UTF-8 databases)\n        return salt.hex(), derived_hash.hex()\n\n    def verify_password(self, plain_password: str, salt_hex: str, stored_hash_hex: str) -> bool:\n        """Verify a plaintext password against stored salt and hash.\n        \n        Args:\n            plain_password: User's plaintext password attempt\n            salt_hex: Hex-encoded salt from storage\n            stored_hash_hex: Hex-encoded hash from storage\n        \n        Returns:\n            True if password matches, False otherwise (constant-time comparison)\n        \n        Raises:\n            ValueError: If salt or hash hex are invalid length\n        """\n        if not plain_password:\n            return False\n        \n        # Decode hex values from storage\n        try:\n            salt = bytes.fromhex(salt_hex)\n            stored_hash = bytes.fromhex(stored_hash_hex)\n        except ValueError as e:\n            raise ValueError(f"Invalid hex encoding for salt or hash: {e}") from e\n        \n        if len(salt) != self.salt_len:\n            raise ValueError(f"Salt length mismatch: expected {self.salt_len}, got {len(salt)}")\n        if len(stored_hash) != self.hash_len:\n            raise ValueError(f"Hash length mismatch: expected {self.hash_len}, got {len(stored_hash)}")\n        \n        # Re-derive hash with same salt and parameters\n        password_bytes = plain_password.encode("utf-8")\n        try:\n            derived_hash = argon2id.kdf(\n                self.hash_len,\n                password_bytes,\n                salt,\n                self.iterations,\n                self.mem_limit\n            )\n        except Exception:\n            # Return False on any derivation error to avoid leaking info\n            return False\n        \n        # Constant-time comparison to prevent timing attacks\n        return hashlib.sha256(derived_hash).digest() == hashlib.sha256(stored_hash).digest()\n\n    def benchmark_cost(self, test_password: str = "test-password-1234") -> dict:\n        """Benchmark current cost parameters, return timing and memory stats."""\n        start_time = time.perf_counter()\n        salt_hex, hash_hex = self.hash_password(test_password)\n        elapsed = time.perf_counter() - start_time\n        verify_result = self.verify_password(test_password, salt_hex, hash_hex)\n        return {\n            "elapsed_seconds": round(elapsed, 4),\n            "mem_limit_mb": self.mem_limit // (1024 * 1024),\n            "iterations": self.iterations,\n            "parallelism": self.parallelism,\n            "verify_success": verify_result\n        }\n\nif __name__ == "__main__":\n    # Example usage and benchmark\n    hasher = PasswordHasher()\n    print("Running Argon2id benchmark with default parameters...")\n    benchmark = hasher.benchmark_cost()\n    print(f"Benchmark results: {benchmark}")\n    \n    # Test hash and verify\n    salt, hash_val = hasher.hash_password("my-secure-password")\n    print(f"Salt: {salt}, Hash: {hash_val}")\n    assert hasher.verify_password("my-secure-password", salt, hash_val) is True\n    assert hasher.verify_password("wrong-password", salt, hash_val) is False\n    print("All tests passed.")\n

# vault.py\n# Requires: pynacl >= 1.5.0, Python 3.12+\nimport os\nimport json\nimport hashlib\nfrom typing import Dict, Any, Optional, Tuple\nfrom nacl.exceptions import BadNonceError, CryptoError\nfrom nacl.bindings import crypto_secretbox_xchacha20poly1305 as xchacha_encrypt, crypto_secretbox_open_xchacha20poly1305 as xchacha_decrypt\n\nclass EncryptedVault:\n    """End-to-end encrypted password vault using XChaCha20-Poly1305 (libsodium)."""\n    \n    # XChaCha20-Poly1305 uses 24-byte nonces, 32-byte keys, 16-byte MAC tags\n    KEY_LEN = 32\n    NONCE_LEN = 24\n    MAC_LEN = 16\n    MAX_VAULT_SIZE = 10 * 1024 * 1024  # 10MB max vault size\n\n    def __init__(self, master_key: Optional[bytes] = None):\n        """Initialize vault with a 32-byte master key.\n        \n        Args:\n            master_key: 32-byte raw key; if None, generates a new random key.\n        \n        Raises:\n            ValueError: If master_key is provided and not 32 bytes.\n        """\n        if master_key is None:\n            self.master_key = os.urandom(self.KEY_LEN)\n        else:\n            if len(master_key) != self.KEY_LEN:\n                raise ValueError(f"master_key must be 32 bytes, got {len(master_key)}")\n            self.master_key = master_key\n\n    def encrypt_vault(self, vault_data: Dict[str, Any]) -> Tuple[str, str, str]:\n        """Encrypt a vault data dict into a serialized, authenticated ciphertext.\n        \n        Args:\n            vault_data: Dict of user's stored credentials (max 10MB when serialized)\n        \n        Returns:\n            Tuple of (nonce_hex, ciphertext_hex, mac_hex)\n        \n        Raises:\n            ValueError: If vault_data is too large or not serializable\n            CryptoError: If encryption fails\n        """\n        # Serialize vault to JSON (UTF-8)\n        try:\n            serialized = json.dumps(vault_data, ensure_ascii=False).encode("utf-8")\n        except (TypeError, ValueError) as e:\n            raise ValueError(f"Vault data is not JSON serializable: {e}") from e\n        \n        if len(serialized) > self.MAX_VAULT_SIZE:\n            raise ValueError(f"Vault size {len(serialized)} bytes exceeds max {self.MAX_VAULT_SIZE}")\n\n        # Generate random nonce (critical: never reuse nonces with same key)\n        try:\n            nonce = os.urandom(self.NONCE_LEN)\n        except Exception as e:\n            raise CryptoError(f"Failed to generate nonce: {e}") from e\n\n        # Encrypt and authenticate with XChaCha20-Poly1305\n        try:\n            # xchacha_encrypt(message, nonce, key) returns ciphertext + MAC (16 bytes)\n            ciphertext_with_mac = xchacha_encrypt(serialized, nonce, self.master_key)\n        except Exception as e:\n            raise CryptoError(f"Vault encryption failed: {e}") from e\n\n        # Split ciphertext (without MAC) and MAC\n        ciphertext = ciphertext_with_mac[:-self.MAC_LEN]\n        mac = ciphertext_with_mac[-self.MAC_LEN:]\n\n        return nonce.hex(), ciphertext.hex(), mac.hex()\n\n    def decrypt_vault(self, nonce_hex: str, ciphertext_hex: str, mac_hex: str) -> Dict[str, Any]:\n        """Decrypt and verify a vault ciphertext.\n        \n        Args:\n            nonce_hex: Hex-encoded 24-byte nonce\n            ciphertext_hex: Hex-encoded encrypted vault data\n            mac_hex: Hex-encoded 16-byte MAC tag\n        \n        Returns:\n            Deserialized vault data dict\n        \n        Raises:\n            ValueError: If hex inputs are invalid length\n            CryptoError: If MAC verification fails (tampered data)\n        """\n        # Decode hex inputs\n        try:\n            nonce = bytes.fromhex(nonce_hex)\n            ciphertext = bytes.fromhex(ciphertext_hex)\n            mac = bytes.fromhex(mac_hex)\n        except ValueError as e:\n            raise ValueError(f"Invalid hex input: {e}") from e\n\n        if len(nonce) != self.NONCE_LEN:\n            raise ValueError(f"Nonce must be {self.NONCE_LEN} bytes, got {len(nonce)}")\n        if len(mac) != self.MAC_LEN:\n            raise ValueError(f"MAC must be {self.MAC_LEN} bytes, got {len(mac)}")\n\n        # Reconstruct ciphertext + MAC for decryption\n        ciphertext_with_mac = ciphertext + mac\n\n        # Decrypt and verify MAC\n        try:\n            serialized = xchacha_decrypt(ciphertext_with_mac, nonce, self.master_key)\n        except CryptoError as e:\n            raise CryptoError(f"Vault decryption failed (tampered data?): {e}") from e\n\n        # Deserialize JSON\n        try:\n            vault_data = json.loads(serialized.decode("utf-8"))\n        except (json.JSONDecodeError, UnicodeDecodeError) as e:\n            raise ValueError(f"Invalid vault data after decryption: {e}") from e\n\n        return vault_data\n\nif __name__ == "__main__":\n    # Example usage\n    vault = EncryptedVault()\n    test_data = {"github.com": "personal-access-token-123", "aws": "AKIA123456789"}\n    nonce, ciphertext, mac = vault.encrypt_vault(test_data)\n    print(f"Nonce: {nonce}, Ciphertext: {ciphertext[:20]}..., MAC: {mac}")\n    decrypted = vault.decrypt_vault(nonce, ciphertext, mac)\n    assert decrypted == test_data\n    print("Vault encrypt/decrypt tests passed.")\n

# totp.py\n# Requires: pyotp >= 2.9.0, qrcode >= 7.4.2 (for provisioning URI), Python 3.12+\nimport base64\nimport hashlib\nimport time\nimport os\nfrom typing import Tuple, Optional, List\nimport pyotp\nimport qrcode\nimport io\n\nclass TOTPManager:\n    """RFC 6238 compliant TOTP multi-factor authentication manager."""\n    \n    # Default TOTP parameters per NIST SP 800-63B: 30-second window, 6-digit code, SHA1 (for compatibility)\n    DEFAULT_DIGITS = 6\n    DEFAULT_INTERVAL = 30  # seconds\n    DEFAULT_SECRET_LEN = 20  # 160-bit secret (RFC 6238 minimum)\n    DEFAULT_DRIFT = 1  # Allow 1 window drift (past/future) to handle clock skew\n\n    def __init__(self, digits: int = DEFAULT_DIGITS, interval: int = DEFAULT_INTERVAL,\n                 secret_len: int = DEFAULT_SECRET_LEN, drift: int = DEFAULT_DRIFT):\n        """Initialize TOTP manager with configurable parameters.\n        \n        Args:\n            digits: Number of digits in TOTP code (6 or 8)\n            interval: Time interval in seconds for code rotation\n            secret_len: Length of TOTP secret in bytes (min 20)\n            drift: Number of adjacent time windows to accept (prevents clock skew issues)\n        """\n        if digits not in (6, 8):\n            raise ValueError(f"digits must be 6 or 8, got {digits}")\n        if interval < 15:\n            raise ValueError(f"interval must be at least 15 seconds, got {interval}")\n        if secret_len < 20:\n            raise ValueError(f"secret_len must be at least 20 bytes, got {secret_len}")\n        self.digits = digits\n        self.interval = interval\n        self.secret_len = secret_len\n        self.drift = drift\n\n    def generate_secret(self) -> str:\n        """Generate a base32-encoded TOTP secret (safe for QR codes and storage).\n        \n        Returns:\n            Base32-encoded secret string (no padding)\n        """\n        raw_secret = pyotp.random_base32()\n        # Trim to desired length and remove padding\n        trimmed = raw_secret[:self.secret_len * 2].rstrip("=")\n        return trimmed\n\n    def get_provisioning_uri(self, secret: str, user_email: str, issuer: str = "AuthPasswordManager") -> str:\n        """Generate a provisioning URI for authenticator apps (Google Auth, Authy).\n        \n        Args:\n            secret: Base32-encoded TOTP secret\n            user_email: User's email (displayed in authenticator app)\n            issuer: Service name (displayed in authenticator app)\n        \n        Returns:\n            otpauth:// URI for QR code generation\n        """\n        totp = pyotp.TOTP(secret, digits=self.digits, interval=self.interval)\n        return totp.provisioning_uri(name=user_email, issuer_name=issuer)\n\n    def generate_qr_code(self, provisioning_uri: str) -> bytes:\n        """Generate a PNG QR code for the provisioning URI.\n        \n        Args:\n            provisioning_uri: otpauth:// URI from get_provisioning_uri\n        \n        Returns:\n            PNG image bytes of the QR code\n        """\n        qr = qrcode.QRCode(version=1, error_correction=qrcode.constants.ERROR_CORRECT_L)\n        qr.add_data(provisioning_uri)\n        qr.make(fit=True)\n        img = qr.make_image(fill_color="black", back_color="white")\n        # Save to bytes buffer\n        buffer = io.BytesIO()\n        img.save(buffer, format="PNG")\n        return buffer.getvalue()\n\n    def verify_code(self, secret: str, user_code: str) -> bool:\n        """Verify a user-provided TOTP code against the secret.\n        \n        Args:\n            secret: Base32-encoded TOTP secret\n            user_code: 6 or 8-digit code provided by user\n        \n        Returns:\n            True if code is valid (within allowed drift), False otherwise\n        \n        Raises:\n            ValueError: If user_code is invalid length or non-numeric\n        """\n        if not user_code.isdigit():\n            raise ValueError("TOTP code must be numeric")\n        if len(user_code) != self.digits:\n            raise ValueError(f"TOTP code must be {self.digits} digits, got {len(user_code)}")\n        \n        totp = pyotp.TOTP(secret, digits=self.digits, interval=self.interval)\n        # Verify with drift to handle clock skew\n        return totp.verify(user_code, valid_window=self.drift)\n\n    def backup_codes(self, count: int = 10) -> List[str]:\n        """Generate one-time backup codes for users who lose their authenticator.\n        \n        Args:\n            count: Number of backup codes to generate (10-20 recommended)\n        \n        Returns:\n            List of 10-character alphanumeric backup codes\n        """\n        if count < 5 or count > 20:\n            raise ValueError(f"count must be between 5 and 20, got {count}")\n        \n        backup_codes = []\n        for _ in range(count):\n            # Generate 10-character code: remove ambiguous chars (0, O, 1, I)\n            raw = base64.b32encode(os.urandom(8)).decode("utf-8").rstrip("=")\n            cleaned = raw.replace("0", "").replace("O", "").replace("1", "").replace("I", "")\n            backup_codes.append(cleaned[:10].upper())\n        return backup_codes\n\nif __name__ == "__main__":\n    # Example usage\n    totp = TOTPManager()\n    secret = totp.generate_secret()\n    print(f"TOTP Secret: {secret}")\n    \n    uri = totp.get_provisioning_uri(secret, "user@example.com")\n    print(f"Provisioning URI: {uri}")\n    \n    qr_bytes = totp.generate_qr_code(uri)\n    with open("totp_qr.png", "wb") as f:\n        f.write(qr_bytes)\n    print("QR code saved to totp_qr.png")\n    \n    # Simulate code verification\n    current_code = pyotp.TOTP(secret).now()\n    print(f"Current TOTP code: {current_code}")\n    assert totp.verify_code(secret, current_code) is True\n    assert totp.verify_code(secret, "123456") is False\n    print("TOTP verification tests passed.")\n    \n    backups = totp.backup_codes(10)\n    print(f"Backup codes: {backups}")\n

from nacl import sodium_init\n\nif not sodium_init():\n    raise RuntimeError("Failed to initialize libsodium")\nprint("Libsodium 1.0.19+ initialized successfully")\n

from password_hashing import PasswordHasher\n\n# Tune for 4-core ARM c7g.large: 256MB mem, 2 iterations, 4 parallelism\narm_hasher = PasswordHasher(\n    mem_limit=256 * 1024 * 1024,\n    iterations=2,\n    parallelism=4\n)\nprint(arm_hasher.benchmark_cost())\n

import hashlib\nimport requests\n\ndef is_password_pwned(plain_password: str) -> bool:\n    sha1 = hashlib.sha1(plain_password.encode("utf-8")).hexdigest().upper()\n    prefix, suffix = sha1[:5], sha1[5:]\n    response = requests.get(f"https://api.pwnedpasswords.com/range/{prefix}")\n    return suffix in response.text\n

password-manager-tutorial/\n├── auth/\n│   ├── __init__.py\n│   ├── password_hashing.py  # Argon2id hasher (code sample 1)\n│   ├── vault.py             # XChaCha20-Poly1305 vault (code sample 2)\n│   ├── totp.py              # TOTP MFA manager (code sample 3)\n│   └── rbac.py              # Role-based access control\n├── api/\n│   ├── __init__.py\n│   ├── auth_routes.py       # FastAPI auth endpoints\n│   └── middleware.py         # Rate limiting, audit logging\n├── tests/\n│   ├── test_hashing.py      # Unit tests for password hasher\n│   ├── test_vault.py        # Unit tests for vault\n│   └── test_totp.py         # Unit tests for TOTP\n├── benchmarks/\n│   ├── hashing_benchmark.py # Argon2id vs bcrypt benchmarks\n│   └── latency_benchmark.py # Auth endpoint latency tests\n├── requirements.txt         # Pinned dependencies (pynacl==1.5.0, pyotp==2.9.0, etc.)\n├── Dockerfile               # Production container image\n└── README.md                # Setup, usage, compliance docs\n