hyperscale-crypto 0.1.0__py3-none-any.whl

hyperscale/crypto/__init__.py

@@ -0,0 +1,3 @@
+"""Application-tier encrypted Django fields backed by Tink keysets and KMS."""
+
+__version__ = "0.1.0"

hyperscale/crypto/apps.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import sys
+
+from django.apps import AppConfig
+
+_SKIP_COMMANDS = {
+    "makemigrations",
+    "migrate",
+    "collectstatic",
+    "check",
+    "showmigrations",
+    "sqlmigrate",
+    "keyset_init",
+    "keyset_status",
+}
+
+
+class HyperscaleCryptoConfig(AppConfig):
+    name = "hyperscale.crypto"
+    label = "hyperscale_crypto"
+    verbose_name = "Hyperscale crypto"
+
+    def ready(self) -> None:
+        from django.db import connection
+
+        from hyperscale.crypto import canary
+        from hyperscale.crypto import keysets
+        from hyperscale.crypto.conf import load_config
+
+        load_config()  # loud defaults: fail at setup, not first use
+        if _SKIP_COMMANDS & set(sys.argv) or "pytest" in sys.argv[0]:
+            return
+        try:
+            if canary.table_ready():
+                # No timer here: under a pre-fork server this is the parent
+                # process, and each worker arms its own on first use.
+                with keysets.without_timer():
+                    canary.check_or_write()
+        finally:
+            # Nor a database connection carried across a fork.
+            connection.close()

hyperscale/crypto/canary.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from django.core.exceptions import ImproperlyConfigured
+from django.db import connection
+from django.db import DatabaseError
+
+from hyperscale.crypto import keysets
+from hyperscale.crypto.encoding import decode
+from hyperscale.crypto.encoding import encode
+from hyperscale.crypto.exceptions import KeysetError
+from hyperscale.crypto.keyset_files import KEYSET_NAMES
+from hyperscale.crypto.models import KeysetCanary
+from hyperscale.crypto.models import KeysetState
+
+CANARY_PLAINTEXT = b"hyperscale.crypto canary"
+_AD = b"hyperscale_crypto.keysetcanary"
+
+
+def table_ready() -> bool:
+    try:
+        return KeysetCanary._meta.db_table in connection.introspection.table_names()
+    except DatabaseError:
+        return False
+
+
+def _load(ks: keysets.Keysets) -> None:
+    """Load (unwrap) both keysets; an error names the keyset that failed."""
+    try:
+        for name in KEYSET_NAMES:
+            ks.proto(name)
+    except KeysetError as exc:
+        raise ImproperlyConfigured(str(exc)) from exc
+
+
+def new_values(ks: keysets.Keysets) -> dict[str, str]:
+    """Fresh canary values under the aead primary and the active daead key."""
+    try:
+        aead_value = encode(ks.aead().encrypt(CANARY_PLAINTEXT, _AD))
+    except Exception as exc:  # KeysetError, tink.TinkError
+        raise ImproperlyConfigured(
+            f"the aead keyset cannot write the canary: {exc}"
+        ) from exc
+    active = KeysetState.load().daead_active_key_id
+    try:
+        daead_value = encode(
+            ks.daead(active).encrypt_deterministically(CANARY_PLAINTEXT, _AD)
+        )
+    except Exception as exc:  # KeysetError, tink.TinkError
+        raise ImproperlyConfigured(
+            f"the daead keyset cannot write the canary under the active key "
+            f"{active}: {exc}"
+        ) from exc
+    return {"aead_value": aead_value, "daead_value": daead_value}
+
+
+def check_or_write() -> None:
+    ks = keysets.get()
+    _load(ks)
+    row = KeysetCanary.objects.filter(pk=1).first()
+    if row is None:
+        row, created = KeysetCanary.objects.get_or_create(pk=1, defaults=new_values(ks))
+        if created:
+            return
+        # Another process wrote it first: verify theirs like any other start.
+    _verify(ks, row)
+
+
+def _verify(ks: keysets.Keysets, row: KeysetCanary) -> None:
+    try:
+        aead_plain = ks.aead().decrypt(decode(row.aead_value), _AD)
+    except Exception as exc:
+        raise ImproperlyConfigured(
+            f"the aead keyset cannot decrypt the stored canary: {exc}"
+        ) from exc
+    if aead_plain != CANARY_PLAINTEXT:
+        raise ImproperlyConfigured(
+            "the aead keyset decrypted the stored canary to the wrong plaintext"
+        )
+    active = KeysetState.load().daead_active_key_id
+    try:
+        daead_plain = ks.daead(active).decrypt_deterministically(
+            decode(row.daead_value), _AD
+        )
+    except Exception as exc:
+        raise ImproperlyConfigured(
+            f"the daead keyset cannot decrypt the stored canary: {exc}"
+        ) from exc
+    if daead_plain != CANARY_PLAINTEXT:
+        raise ImproperlyConfigured(
+            "the daead keyset decrypted the stored canary to the wrong plaintext"
+        )
+
+
+def reencrypt_aead() -> bool:
+    """Move the stored aead canary to the current primary; False if nothing moved.
+
+    Rotation calls this so retiring the old key leaves the canary readable.
+    """
+    ks = keysets.get()
+    row = KeysetCanary.objects.select_for_update().filter(pk=1).first()
+    if row is None:
+        return False
+    raw = decode(row.aead_value)
+    if keysets.key_id_of(raw) == ks.primary_key_id("aead"):
+        return False
+    plain = ks.aead().decrypt(raw, _AD)
+    row.aead_value = encode(ks.aead().encrypt(plain, _AD))
+    row.save(update_fields=["aead_value"])
+    return True
+
+
+def reencrypt_daead(key_id: int) -> bool:
+    """Move the stored daead canary to `key_id`; False if nothing moved."""
+    ks = keysets.get()
+    row = KeysetCanary.objects.select_for_update().filter(pk=1).first()
+    if row is None:
+        return False
+    raw = decode(row.daead_value)
+    if keysets.key_id_of(raw) == key_id:
+        return False
+    target = ks.daead(key_id)  # decrypts under any enabled key
+    plain = target.decrypt_deterministically(raw, _AD)
+    row.daead_value = encode(target.encrypt_deterministically(plain, _AD))
+    row.save(update_fields=["daead_value"])
+    return True

hyperscale/crypto/conf.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from typing import cast
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+
+MODES = ("kms", "cleartext")
+_KMS_URI_SCHEMES = ("aws-kms://", "fake-kms://")
+_KNOWN = {
+    "mode",
+    "kms_key_uri",
+    "keyset_dir",
+    "reunwrap_seconds",
+    "revoke_on_reunwrap_failure",
+    "retention_days",
+    "git_sha",
+}
+
+
+@dataclass(frozen=True)
+class CryptoConfig:
+    mode: str
+    kms_key_uri: str
+    keyset_dir: Path
+    reunwrap_seconds: int
+    revoke_on_reunwrap_failure: bool
+    retention_days: int
+    git_sha: str
+
+
+def environment_allows_cleartext() -> bool:
+    return os.environ.get("ENV", "") in ("development", "test")
+
+
+def is_fake_kms(uri: str) -> bool:
+    return uri.startswith("fake-kms://")
+
+
+def _positive_int(cfg: dict[str, Any], key: str, default: int) -> int:
+    value = cfg.get(key, default)
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ImproperlyConfigured(
+            f"HYPERSCALE_CRYPTO['{key}'] must be a positive integer, not {value!r}"
+        )
+    return value
+
+
+def load_config() -> CryptoConfig:
+    raw: Any = getattr(settings, "HYPERSCALE_CRYPTO", None)
+    if not isinstance(raw, dict):
+        raise ImproperlyConfigured("HYPERSCALE_CRYPTO must be set to a dict")
+    cfg = cast("dict[str, Any]", raw)
+    unknown = set(cfg) - _KNOWN
+    if unknown:
+        raise ImproperlyConfigured(
+            f"HYPERSCALE_CRYPTO has unknown key(s): {', '.join(sorted(unknown))}"
+        )
+    mode = cfg.get("mode", "kms")
+    if mode not in MODES:
+        raise ImproperlyConfigured(f"HYPERSCALE_CRYPTO['mode'] must be one of {MODES}")
+    key_uri = str(cfg.get("kms_key_uri", "") or "")
+    reunwrap = _positive_int(cfg, "reunwrap_seconds", 900)
+    retention = _positive_int(cfg, "retention_days", 35)
+    revoke = cfg.get("revoke_on_reunwrap_failure", False)
+    if not isinstance(revoke, bool):
+        raise ImproperlyConfigured(
+            "HYPERSCALE_CRYPTO['revoke_on_reunwrap_failure'] must be True or "
+            f"False, not {revoke!r}"
+        )
+    if "keyset_dir" not in cfg:
+        raise ImproperlyConfigured("HYPERSCALE_CRYPTO['keyset_dir'] is required")
+    if mode == "kms" and not key_uri:
+        raise ImproperlyConfigured(
+            "HYPERSCALE_CRYPTO['kms_key_uri'] is required in kms mode"
+        )
+    if mode == "kms" and not key_uri.startswith(_KMS_URI_SCHEMES):
+        raise ImproperlyConfigured(
+            "HYPERSCALE_CRYPTO['kms_key_uri'] must start with "
+            f"{' or '.join(_KMS_URI_SCHEMES)}"
+        )
+    if mode == "cleartext" and not environment_allows_cleartext():
+        raise ImproperlyConfigured(
+            "HYPERSCALE_CRYPTO mode 'cleartext' is only allowed when ENV is "
+            "development or test"
+        )
+    if is_fake_kms(key_uri) and not environment_allows_cleartext():
+        raise ImproperlyConfigured(
+            "a fake-kms:// key URI is only allowed when ENV is development or test"
+        )
+    return CryptoConfig(
+        mode=mode,
+        kms_key_uri=key_uri,
+        keyset_dir=Path(cfg["keyset_dir"]),
+        reunwrap_seconds=reunwrap,
+        revoke_on_reunwrap_failure=revoke,
+        retention_days=retention,
+        git_sha=str(cfg.get("git_sha", os.environ.get("GIT_SHA", ""))),
+    )

hyperscale/crypto/encoding.py

@@ -0,0 +1,26 @@
+"""The `hc1:` storage encoding of a raw Tink ciphertext."""
+
+from __future__ import annotations
+
+import base64
+
+from hyperscale.crypto.exceptions import DecryptionError
+
+PREFIX = "hc1:"
+
+
+def encode(raw: bytes) -> str:
+    return PREFIX + base64.urlsafe_b64encode(raw).decode("ascii")
+
+
+def is_encoded(value: object) -> bool:
+    return isinstance(value, str) and value.startswith(PREFIX)
+
+
+def decode(text: str) -> bytes:
+    if not is_encoded(text):
+        raise DecryptionError("stored value is not an hc1 ciphertext")
+    try:
+        return base64.urlsafe_b64decode(text[len(PREFIX) :])
+    except ValueError as exc:
+        raise DecryptionError("stored ciphertext is not valid base64") from exc

hyperscale/crypto/exceptions.py

@@ -0,0 +1,10 @@
+class CryptoError(Exception):
+    """Base for every error this package raises at runtime."""
+
+
+class DecryptionError(CryptoError):
+    """A stored value could not be decrypted (wrong key, wrong context, corrupt)."""
+
+
+class KeysetError(CryptoError):
+    """A keyset file or keyset state is unusable."""