secure-keystore 3.0.0__py3-none-any.whl

secure_keystore/__init__.py

@@ -0,0 +1,96 @@
+"""secure-keystore: encrypted secrets at rest, with no service to run.
+
+Two ways in, for different things:
+
+1. **A store.** A directory of encrypted values that one user key opens. The
+   store owns a master key, one salt per value, and a catalogue - so an
+   application deploys a directory and reads secrets out of it at run time. That
+   is :class:`Keystore`.
+2. **A token.** One string in, one string out, nothing on disk. The application
+   already has somewhere to put it - a database column, a config row - and only
+   wants the value unreadable while it sits there. That is :func:`encrypt_value`
+   and :func:`decrypt_value`.
+
+Both use the same primitives: AES-256-GCM to encrypt, PBKDF2-HMAC-SHA256 to
+stretch the user key, HKDF-SHA256 to derive a value key from the master key. A
+fresh random salt and IV every time.
+
+.. code-block:: python
+
+    from secure_keystore import Keystore
+
+    store = Keystore()
+    store.secure("./keys.env", os.environ["USER_KEY"], "production")
+    api_key = store.get("api_key", os.environ["USER_KEY"], "production")
+
+**Which KDF, and why two.** A user key is a password, so it is stretched:
+deliberately slow, 600,000 rounds by default. A master key is not a password - it
+is already a strong secret - so value keys come from HKDF, which is fast.
+Stretching the master key once per value, which format 2.0 did, costs seconds on
+a store of any size and buys nothing.
+
+The on-disk format is specified in SPEC.md at the root of the repository, and
+this implementation reads and writes the same bytes as the JavaScript, Go, .NET,
+PHP and Rust ones - which is not a claim but a test, in ``tests/test_conformance.py``.
+"""
+
+from __future__ import annotations
+
+from ._format import (
+    BACKUP_VERSION,
+    DEFAULT_ITERATIONS,
+    STORE_FORMAT_LEGACY,
+    STORE_FORMAT_VERSION,
+    VALUE_TOKEN_PREFIX,
+)
+from .errors import ErrorCodes, KeystoreError
+from .input_file import Entry, InputFormat, ParsedInput, format_for, parse_input, parse_text
+from .keystore import Keystore, MigrateResult, SecureResult, SetResult, StoreInfo
+from .token import decrypt_value, encrypt_value, is_encrypted_value, token_version
+
+#: The version of this implementation, which is not the same thing as the
+#: version of the store format (:data:`STORE_FORMAT_VERSION`).
+__version__ = "3.0.0"
+
+#: What this build actually does, in one mapping, so that a caller who has to
+#: write it down in a compliance document does not have to read the source.
+ALGORITHMS = {
+    "cipher": "aes-256-gcm",
+    "ivBytes": 12,
+    # How the user key - a password - is stretched. Deliberately slow.
+    "passwordKdf": "pbkdf2-hmac-sha256",
+    "defaultIterations": DEFAULT_ITERATIONS,
+    # How a value key comes from the master key. Fast, and correctly so.
+    "keyKdf": "hkdf-sha256",
+    "digest": "sha256",
+    "keyBits": 256,
+    # Whether a value is cryptographically bound to its key name.
+    "bindsKeyName": True,
+}
+
+__all__ = [
+    "Keystore",
+    "KeystoreError",
+    "ErrorCodes",
+    "StoreInfo",
+    "SecureResult",
+    "SetResult",
+    "MigrateResult",
+    "encrypt_value",
+    "decrypt_value",
+    "is_encrypted_value",
+    "token_version",
+    "InputFormat",
+    "Entry",
+    "ParsedInput",
+    "format_for",
+    "parse_input",
+    "parse_text",
+    "ALGORITHMS",
+    "STORE_FORMAT_VERSION",
+    "STORE_FORMAT_LEGACY",
+    "BACKUP_VERSION",
+    "VALUE_TOKEN_PREFIX",
+    "DEFAULT_ITERATIONS",
+    "__version__",
+]

secure_keystore/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m secure_keystore``."""
+
+from .cli import main
+
+raise SystemExit(main())

secure_keystore/_crypto.py

@@ -0,0 +1,181 @@
+"""The cryptographic primitives, and nothing else.
+
+Every AES call in this package goes through this module, so there is exactly one
+place where an algorithm, an IV length or an encoding is chosen.
+
+Two derivations, for two different jobs, which format 2.0 conflated:
+
+``stretch_password``
+    A *password* into a key. Deliberately slow. Used once per store, on the user
+    key, and on every value token.
+
+``derive_from_key``
+    A key into another key. Fast, because the input is already high-entropy key
+    material and stretching it buys nothing.
+
+Running 600,000 PBKDF2 rounds on the master key once per value - which 2.0 did -
+costs seconds on a store of any size and adds no security the master key did not
+already have. That is the misuse HKDF exists to correct.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+from . import _format as fmt
+from .errors import ErrorCodes, KeystoreError
+
+
+@dataclass(slots=True)
+class Encrypted:
+    """One AES-GCM result, as it appears in a store file. Every field is hex."""
+
+    iv: str
+    auth_tag: str
+    data: str
+
+    def to_json(self) -> dict[str, str]:
+        return {"iv": self.iv, "authTag": self.auth_tag, "data": self.data}
+
+    @staticmethod
+    def from_json(raw: Any, what: str = "value") -> "Encrypted":
+        if not isinstance(raw, dict):
+            raise KeystoreError(
+                ErrorCodes.STORE_CORRUPT, f"the encrypted {what} is not an object"
+            )
+
+        iv, auth_tag, data = raw.get("iv"), raw.get("authTag"), raw.get("data")
+        if not isinstance(iv, str) or not isinstance(auth_tag, str) or not isinstance(data, str):
+            raise KeystoreError(
+                ErrorCodes.STORE_CORRUPT,
+                f"the encrypted {what} is missing its iv, authTag or data",
+            )
+
+        return Encrypted(iv=iv, auth_tag=auth_tag, data=data)
+
+
+def random_bytes(length: int) -> bytes:
+    """Random bytes from the system source."""
+    return os.urandom(length)
+
+
+def stretch_password(password: str, salt: bytes, iterations: int) -> bytes:
+    """PBKDF2-HMAC-SHA256: a password, stretched.
+
+    The count is a parameter rather than a constant because it is recorded
+    alongside whatever it derives. Deriving with a count that does not match the
+    one a record was written with produces a different key, and the GCM tag then
+    rejects it - which is the failure you want rather than the one where it
+    nearly works.
+    """
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=fmt.KEY_LENGTH,
+        salt=salt,
+        iterations=iterations,
+    )
+    return kdf.derive(password.encode("utf-8"))
+
+
+def derive_from_key(key: str, salt: bytes, info: str) -> bytes:
+    """HKDF-SHA256: one key into another, bound to a context.
+
+    The input is the master key, which is already a strong secret, so there is
+    nothing to stretch - the job is separation, not hardening. ``info`` carries
+    the context that separates them, and for a value that context contains the
+    key name, which is half of what stops two value files being swapped. The
+    other half is the same string passed as GCM additional data.
+    """
+    kdf = HKDF(
+        algorithm=hashes.SHA256(),
+        length=fmt.KEY_LENGTH,
+        salt=salt,
+        info=info.encode("utf-8"),
+    )
+    return kdf.derive(key.encode("utf-8"))
+
+
+def encrypt(plaintext: str, key: bytes, iv_length: int = fmt.IV_LENGTH, aad: str = "") -> Encrypted:
+    """Seal a plaintext under a fresh random IV.
+
+    The same plaintext under the same key never produces the same bytes twice.
+    ``aad`` is empty for a format 2.0 record, which bound nothing.
+    """
+    iv = random_bytes(iv_length)
+    associated = aad.encode("utf-8") if aad else None
+
+    # AESGCM.encrypt returns ciphertext with the tag appended; the format stores
+    # them as separate hex fields.
+    sealed = AESGCM(key).encrypt(iv, plaintext.encode("utf-8"), associated)
+    split = len(sealed) - fmt.AUTH_TAG_LENGTH
+
+    return Encrypted(
+        iv=iv.hex(),
+        auth_tag=sealed[split:].hex(),
+        data=sealed[:split].hex(),
+    )
+
+
+def decrypt(record: Encrypted, key: bytes, aad: str = "", what: str = "value") -> str:
+    """Reverse :func:`encrypt`, and translate the failure.
+
+    GCM cannot tell a wrong key from tampered bytes from mismatched additional
+    data - all three are a tag that does not verify - and ``cryptography``
+    reports any of them as :class:`InvalidTag`, which tells a caller nothing.
+    All three become ``BAD_USER_KEY`` here.
+    """
+    try:
+        iv = bytes.fromhex(record.iv)
+        tag = bytes.fromhex(record.auth_tag)
+        data = bytes.fromhex(record.data)
+    except ValueError as cause:
+        raise KeystoreError(
+            ErrorCodes.STORE_CORRUPT, f"the encrypted {what} has a malformed hex field"
+        ) from cause
+
+    if not iv:
+        raise KeystoreError(ErrorCodes.STORE_CORRUPT, f"the encrypted {what} has an empty iv")
+
+    associated = aad.encode("utf-8") if aad else None
+
+    try:
+        plaintext = AESGCM(key).decrypt(iv, data + tag, associated)
+    except (InvalidTag, ValueError) as cause:
+        raise KeystoreError(
+            ErrorCodes.BAD_USER_KEY,
+            f"could not decrypt the {what}: the key is wrong, "
+            "or the stored bytes have been altered",
+        ) from cause
+
+    return plaintext.decode("utf-8")
+
+
+def safe_file_name(key: str) -> str:
+    """A filesystem-safe, collision-resistant filename for a key.
+
+    The stem is for humans, so it is the key with anything unsafe replaced -
+    which neutralises ``../``, drive letters and the characters Windows refuses.
+    Sanitising alone would map ``a/b`` and ``a_b`` onto one file, so the real
+    identity is the hash suffix; the stem is only a label.
+
+    The stem is built from UTF-8 *bytes* and truncated by bytes, matching every
+    other implementation. A multi-byte character straddling the limit is cut, but
+    the name is a label and the hash is the identity, so a mangled label costs
+    nothing.
+    """
+    raw = key.encode("utf-8")
+    allowed = set(b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._-")
+
+    stem = bytes(byte if byte in allowed else ord("_") for byte in raw[: fmt.FILENAME_STEM_LIMIT])
+    digest = hashlib.sha256(raw).hexdigest()[: fmt.FILENAME_HASH_LENGTH]
+
+    return f"{stem.decode('ascii')}-{digest}{fmt.VALUE_EXTENSION}"

secure_keystore/_format.py

@@ -0,0 +1,118 @@
+"""Wire-format constants for the secure-keystore format.
+
+Nothing here is a tuning knob. These are the values that define what a store
+written by this package looks like, and changing one changes what the other five
+implementations can read - which is why they live in one module rather than
+scattered through the code that happens to use them.
+
+Two format versions appear throughout. 3.0 is what this build writes; 2.0 is
+what earlier releases wrote and what this build still reads. Everywhere the two
+differ, the legacy value is named ``*_LEGACY`` and the difference is a parameter
+rather than a separate code path.
+"""
+
+from __future__ import annotations
+
+#: The store format stamped into every master.json this build writes.
+STORE_FORMAT_VERSION = "3.0"
+
+#: The older format this build still reads and, on a store already written that
+#: way, still writes.
+STORE_FORMAT_LEGACY = "2.0"
+
+#: Identifies an export bundle, checked before anything is written to disk.
+BACKUP_FORMAT = "secure-keystore-backup"
+
+#: The bundle format this build writes and the highest it reads.
+BACKUP_VERSION = 1
+
+# Value token layouts. skv2 records its own iteration count, which is the one
+# thing skv1 got wrong: a token that cannot say how it was derived is a token
+# whose parameters can never change.
+#
+#   skv1:<salt>:<iv>:<authTag>:<ciphertext>
+#   skv2:<iterations>:<salt>:<iv>:<authTag>:<ciphertext>
+VALUE_TOKEN_PREFIX = "skv2"
+VALUE_TOKEN_PARTS = 6
+VALUE_TOKEN_PREFIX_LEGACY = "skv1"
+VALUE_TOKEN_PARTS_LEGACY = 5
+
+#: AES-256: a 32-byte key.
+KEY_LENGTH = 32
+
+#: 12 bytes, which is what NIST SP 800-38D recommends for GCM and the only
+#: length several platforms accept at all - .NET's AesGcm refuses anything else.
+IV_LENGTH = 12
+
+#: The 16 bytes format 2.0 wrote.
+IV_LENGTH_LEGACY = 16
+
+#: The GCM tag length, and the only one this format uses.
+AUTH_TAG_LENGTH = 16
+
+#: What a new store stretches the user key with, following OWASP's 2023 guidance
+#: for PBKDF2-HMAC-SHA256.
+DEFAULT_ITERATIONS = 600_000
+
+#: The floor below which the option is refused. Test suites run at this.
+MIN_ITERATIONS = 10_000
+
+#: Assumed for any 2.0 record written before the count was recorded.
+LEGACY_ITERATIONS = 100_000
+
+#: Fixed by the skv1 layout, which has no field to record a count in.
+TOKEN_ITERATIONS_LEGACY = 100_000
+
+STORE_SALT_LENGTH = 32
+VALUE_SALT_LENGTH = 32
+
+#: 16, because the token carries its salt inline, in hex, in every stored value.
+TOKEN_SALT_LENGTH = 16
+
+# Domain-separation contexts, used as GCM additional authenticated data and, for
+# a value, as the HKDF info as well.
+#
+# This is what closes the gap 2.0 had: there, the tag covered the ciphertext and
+# nothing else, so anyone who could write to a store could swap two value files
+# and both would decrypt - under each other's names.
+CONTEXT_MASTER = "secure-keystore:v3:master"
+CONTEXT_VALUE_PREFIX = "secure-keystore:v3:value:"
+CONTEXT_TOKEN = "secure-keystore:v3:token"
+
+
+def value_context(key_name: str) -> str:
+    """The full context string binding a value to its key name."""
+    return CONTEXT_VALUE_PREFIX + key_name
+
+
+#: Catalogue of stores: names and key names, no secrets.
+INDEX_FILE = "index.json"
+
+#: Per-store metadata and the encrypted master key.
+MASTER_FILE = "master.json"
+
+#: One authenticated-encrypted file per value.
+VALUE_EXTENSION = ".enc"
+
+#: Created under the working directory when no keystore directory is given.
+DEFAULT_KEYSTORE_DIRNAME = ".keystore"
+
+#: What ``export_store`` writes when given no path.
+DEFAULT_BACKUP_EXTENSION = ".skb"
+
+#: The name an input file uses for the master key, in every input format.
+MASTER_ENTRY_KEY = "master"
+
+# Value filenames are a readable stem plus a hash of the key. The stem may
+# collide between two different keys; the hash is what keeps their files apart.
+FILENAME_STEM_LIMIT = 64
+FILENAME_HASH_LENGTH = 8
+
+
+def major_of(version: str) -> int:
+    """The major part of a version string, or 0 if it is not a number."""
+    head = version.split(".", 1)[0]
+    try:
+        return int(head)
+    except ValueError:
+        return 0

secure_keystore/bundle.py

@@ -0,0 +1,108 @@
+"""Export and import, as one JSON bundle.
+
+The contents are already encrypted, so a bundle is safe to put through a CI
+artifact store or an ``scp``, and useless to anyone who intercepts it without the
+user key. It is pure JSON - no tar, no shell - so it behaves the same on every
+platform.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from . import _format as fmt
+from .errors import ErrorCodes, KeystoreError
+
+__all__ = ["build_bundle", "read_bundle", "write_bundle"]
+
+
+def build_bundle(store_dir: Path, store_name: str) -> dict[str, Any]:
+    """Read every file in a store directory into a bundle."""
+    return {
+        "format": fmt.BACKUP_FORMAT,
+        "version": fmt.BACKUP_VERSION,
+        "storeName": store_name,
+        "files": {
+            path.name: path.read_text(encoding="utf-8")
+            for path in sorted(store_dir.iterdir())
+            if path.is_file()
+        },
+    }
+
+
+def read_bundle(backup_path: str | Path) -> dict[str, Any]:
+    """Read a bundle off disk and check it is one of ours before any of it is believed.
+
+    The checks are in the order that matters: a file that is not JSON, a JSON
+    document that is not a bundle, a bundle from a future version, and a bundle
+    with no master.json are four different mistakes and each says so.
+    """
+    path = Path(backup_path)
+    if not path.is_file():
+        raise KeystoreError(ErrorCodes.BAD_BACKUP, f"backup file not found: {backup_path}")
+
+    try:
+        bundle = json.loads(path.read_text(encoding="utf-8"))
+    except (ValueError, OSError) as cause:
+        raise KeystoreError(
+            ErrorCodes.BAD_BACKUP,
+            f"invalid backup file: {backup_path} is not readable as JSON",
+        ) from cause
+
+    if (
+        not isinstance(bundle, dict)
+        or bundle.get("format") != fmt.BACKUP_FORMAT
+        or not isinstance(bundle.get("files"), dict)
+    ):
+        raise KeystoreError(
+            ErrorCodes.BAD_BACKUP, f"invalid backup file: {backup_path} is not a keystore bundle"
+        )
+
+    version = bundle.get("version", 0)
+    if isinstance(version, int) and version > fmt.BACKUP_VERSION:
+        raise KeystoreError(
+            ErrorCodes.UNSUPPORTED_FORMAT,
+            f"backup was written in bundle format {version}, "
+            f"and this build reads up to {fmt.BACKUP_VERSION}",
+        )
+
+    if fmt.MASTER_FILE not in bundle["files"]:
+        raise KeystoreError(
+            ErrorCodes.BAD_BACKUP, f"invalid backup: {fmt.MASTER_FILE} not found in bundle"
+        )
+
+    return bundle
+
+
+def write_bundle(bundle: dict[str, Any], target_dir: Path) -> None:
+    """Write a bundle's files into a target directory.
+
+    Every name is reduced to its base name first. A bundle is an untrusted file
+    that arrived over a wire, and ``{"files": {"../../.ssh/authorized_keys": ...}}``
+    is a bundle someone could write by hand.
+
+    ``PurePath.name`` alone is not enough for a Windows path arriving on Unix or
+    the reverse, so both separators are handled explicitly.
+    """
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    for name, content in bundle["files"].items():
+        safe = _base_name(str(name))
+        if safe in ("", ".", ".."):
+            continue
+        (target_dir / safe).write_text(content, encoding="utf-8")
+
+
+def _base_name(name: str) -> str:
+    """Strip every directory component, whichever separator was used."""
+    for index in range(len(name) - 1, -1, -1):
+        if name[index] in ("/", "\\"):
+            return name[index + 1 :]
+
+    # A drive-relative name like "C:evil.txt" has no separator at all.
+    if len(name) > 1 and name[1] == ":":
+        return name[2:]
+
+    return name