Section 31 point 1: admin credentials, signed session, and CSRF
This commit is contained in:
1 parent
55f76d0991
commit
d33be384bd
1 file changed
+196
@@ -0,0 +1,196 @@
|
||||
"""Admin credentials, signed sessions, and CSRF tokens for VardKey.
|
||||
|
||||
Section 31 point 1 puts the whole app behind an admin login. This module is the
|
||||
only place that knows how the credential is stored and how a session is proven:
|
||||
|
||||
- The password is stored **only** as a ``hashlib.scrypt`` hash with a random
|
||||
salt per password, and compared with ``hmac.compare_digest``. No hand-written
|
||||
cryptography is involved, and the admin password is the only credential the
|
||||
app stores — it is an app login, not a wallet secret.
|
||||
- A session is a signed cookie: HMAC-SHA256 over an expiry timestamp, keyed by a
|
||||
``session_secret`` that is generated once and kept in ``app_settings``. There
|
||||
is no session table, so a session survives a restart.
|
||||
- A CSRF token is a double-submit value: the same random token in a readable
|
||||
cookie and in a request header, compared with ``hmac.compare_digest``.
|
||||
|
||||
The three settings live in the ``app_settings`` table from section 31 point 7,
|
||||
so no new table is needed.
|
||||
"""
|
||||
|
||||
import hashlib
|
||||
import hmac
|
||||
import secrets
|
||||
from datetime import datetime, timedelta, timezone
|
||||
|
||||
from database import get_app_settings, save_app_settings
|
||||
|
||||
|
||||
ADMIN_USERNAME_SETTING = "admin_username"
|
||||
ADMIN_PASSWORD_HASH_SETTING = "admin_password_hash"
|
||||
SESSION_SECRET_SETTING = "session_secret"
|
||||
|
||||
SESSION_COOKIE = "vardkey_session"
|
||||
CSRF_COOKIE = "vardkey_csrf"
|
||||
CSRF_HEADER = "X-CSRF-Token"
|
||||
|
||||
# A month is long enough that the single local user is not asked to log in again
|
||||
# on every visit, and the cookie is still bounded.
|
||||
SESSION_TTL_SECONDS = 30 * 24 * 60 * 60
|
||||
|
||||
# ``hashlib.scrypt`` parameters. The salt is random per password, so two equal
|
||||
# passwords never share a hash. 2**14 needs 16 MiB, which is inside OpenSSL's
|
||||
# default memory limit.
|
||||
SCRYPT_N = 2**14
|
||||
SCRYPT_R = 8
|
||||
SCRYPT_P = 1
|
||||
SCRYPT_DKLEN = 32
|
||||
SCRYPT_SALT_BYTES = 16
|
||||
SCRYPT_PREFIX = "scrypt"
|
||||
|
||||
|
||||
def hash_password(password):
|
||||
"""Return a self-describing scrypt hash for the password.
|
||||
|
||||
The stored value carries its own parameters and salt, so the format can be
|
||||
changed later without invalidating an existing password.
|
||||
"""
|
||||
salt = secrets.token_bytes(SCRYPT_SALT_BYTES)
|
||||
digest = hashlib.scrypt(
|
||||
password.encode("utf-8"),
|
||||
salt=salt,
|
||||
n=SCRYPT_N,
|
||||
r=SCRYPT_R,
|
||||
p=SCRYPT_P,
|
||||
dklen=SCRYPT_DKLEN,
|
||||
)
|
||||
return (
|
||||
f"{SCRYPT_PREFIX}${SCRYPT_N}${SCRYPT_R}${SCRYPT_P}"
|
||||
f"${salt.hex()}${digest.hex()}"
|
||||
)
|
||||
|
||||
|
||||
def verify_password(password, stored):
|
||||
"""Return True when the password matches the stored hash.
|
||||
|
||||
A malformed stored value is a failed match, never an error, so a broken row
|
||||
cannot be turned into a traceback.
|
||||
"""
|
||||
if not isinstance(stored, str) or not isinstance(password, str):
|
||||
return False
|
||||
parts = stored.split("$")
|
||||
if len(parts) != 6 or parts[0] != SCRYPT_PREFIX:
|
||||
return False
|
||||
_, n, r, p, salt_hex, digest_hex = parts
|
||||
try:
|
||||
salt = bytes.fromhex(salt_hex)
|
||||
expected = bytes.fromhex(digest_hex)
|
||||
digest = hashlib.scrypt(
|
||||
password.encode("utf-8"),
|
||||
salt=salt,
|
||||
n=int(n),
|
||||
r=int(r),
|
||||
p=int(p),
|
||||
dklen=len(expected),
|
||||
)
|
||||
except (ValueError, TypeError):
|
||||
return False
|
||||
return hmac.compare_digest(digest, expected)
|
||||
|
||||
|
||||
def get_admin(database_path="data/vardkey.sqlite3"):
|
||||
"""Return the stored ``(username, password_hash)``, either of which may be None."""
|
||||
settings = get_app_settings(database_path)
|
||||
return (
|
||||
settings.get(ADMIN_USERNAME_SETTING),
|
||||
settings.get(ADMIN_PASSWORD_HASH_SETTING),
|
||||
)
|
||||
|
||||
|
||||
def admin_configured(database_path="data/vardkey.sqlite3"):
|
||||
"""Return True when an admin username and password are stored.
|
||||
|
||||
The first run has none, and the app answers with the create-admin page
|
||||
instead of the login form (section 31 point 1).
|
||||
"""
|
||||
username, password_hash = get_admin(database_path)
|
||||
return bool(username and password_hash)
|
||||
|
||||
|
||||
def set_admin(username, password, database_path="data/vardkey.sqlite3"):
|
||||
"""Store the admin username and the scrypt hash of the password."""
|
||||
save_app_settings(
|
||||
{
|
||||
ADMIN_USERNAME_SETTING: username,
|
||||
ADMIN_PASSWORD_HASH_SETTING: hash_password(password),
|
||||
},
|
||||
database_path,
|
||||
)
|
||||
|
||||
|
||||
def authenticate(username, password, database_path="data/vardkey.sqlite3"):
|
||||
"""Return True when the credentials match the stored admin."""
|
||||
stored_username, stored_hash = get_admin(database_path)
|
||||
if not stored_username or not stored_hash:
|
||||
return False
|
||||
if not isinstance(username, str):
|
||||
return False
|
||||
# Both comparisons run, so a wrong username and a wrong password are equally
|
||||
# slow.
|
||||
username_ok = hmac.compare_digest(username, stored_username)
|
||||
password_ok = verify_password(password, stored_hash)
|
||||
return username_ok and password_ok
|
||||
|
||||
|
||||
def session_secret(database_path="data/vardkey.sqlite3"):
|
||||
"""Return the session secret, generating and storing it once."""
|
||||
stored = get_app_settings(database_path).get(SESSION_SECRET_SETTING)
|
||||
if stored:
|
||||
return stored
|
||||
secret = secrets.token_hex(32)
|
||||
save_app_settings({SESSION_SECRET_SETTING: secret}, database_path)
|
||||
return secret
|
||||
|
||||
|
||||
def _sign(secret, payload):
|
||||
"""Return the HMAC-SHA256 signature of a payload, as hex."""
|
||||
return hmac.new(
|
||||
secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256
|
||||
).hexdigest()
|
||||
|
||||
|
||||
def create_session_token(database_path="data/vardkey.sqlite3", now=None):
|
||||
"""Return a signed session token that expires after the session lifetime."""
|
||||
moment = now or datetime.now(timezone.utc)
|
||||
expires = int((moment + timedelta(seconds=SESSION_TTL_SECONDS)).timestamp())
|
||||
payload = str(expires)
|
||||
return f"{payload}.{_sign(session_secret(database_path), payload)}"
|
||||
|
||||
|
||||
def verify_session_token(token, database_path="data/vardkey.sqlite3", now=None):
|
||||
"""Return True when the token is signed correctly and has not expired."""
|
||||
if not isinstance(token, str) or "." not in token:
|
||||
return False
|
||||
payload, _, signature = token.partition(".")
|
||||
expected = _sign(session_secret(database_path), payload)
|
||||
if not hmac.compare_digest(signature, expected):
|
||||
return False
|
||||
try:
|
||||
expires = int(payload)
|
||||
except ValueError:
|
||||
return False
|
||||
moment = now or datetime.now(timezone.utc)
|
||||
return expires > int(moment.timestamp())
|
||||
|
||||
|
||||
def new_csrf_token():
|
||||
"""Return a fresh CSRF token."""
|
||||
return secrets.token_hex(32)
|
||||
|
||||
|
||||
def csrf_tokens_match(cookie_value, header_value):
|
||||
"""Return True when the CSRF cookie and the CSRF header are the same token."""
|
||||
if not cookie_value or not header_value:
|
||||
return False
|
||||
if not isinstance(cookie_value, str) or not isinstance(header_value, str):
|
||||
return False
|
||||
return hmac.compare_digest(cookie_value, header_value)
|
||||
Reference in new issue
Block a user