Add keyfile creation support (#48)

coreyleavitt · web-flow · commit fbef7fb54533 · 2025-12-10T00:56:28.000-06:00
Add keyfile creation support Add new security/keyfile.py module with support for creating KeePass keyfiles in all supported formats: - XML v2.0 (.keyx): Recommended format with hex-encoded key and SHA-256 hash verification - XML v1.0 (.key): Legacy format with base64-encoded key - RAW_32: Raw 32-byte binary key - HEX_64: 64-character hex string New public API: - create_keyfile(path, version) - create keyfile at path - create_keyfile_bytes(version) - return keyfile as bytes - parse_keyfile(data) - parse keyfile and extract key - KeyFileVersion enum for format selection Refactored _process_keyfile() from kdf.py to parse_keyfile() in the new keyfile module for better organization. Closes #47
diff --git a/src/kdbxtool/__init__.py b/src/kdbxtool/__init__.py
@@ -54,6 +54,12 @@
 )
 from .models import Attachment, Entry, Group, HistoryEntry, Times
 from .security import AesKdfConfig, Argon2Config, Cipher, KdfType
+from .security.keyfile import (
+    KeyFileVersion,
+    create_keyfile,
+    create_keyfile_bytes,
+    parse_keyfile,
+)
 from .security.yubikey import (
     YubiKeyConfig,
     check_slot_configured,
@@ -74,6 +80,11 @@
     "Times",
     "Cipher",
     "KdfType",
+    # Keyfile support
+    "KeyFileVersion",
+    "create_keyfile",
+    "create_keyfile_bytes",
+    "parse_keyfile",
     # YubiKey support
     "YubiKeyConfig",
     "check_slot_configured",
diff --git a/src/kdbxtool/security/__init__.py b/src/kdbxtool/security/__init__.py
@@ -28,6 +28,12 @@
     derive_key_aes_kdf,
     derive_key_argon2,
 )
+from .keyfile import (
+    KeyFileVersion,
+    create_keyfile,
+    create_keyfile_bytes,
+    parse_keyfile,
+)
 from .memory import SecureBytes
 from .yubikey import (
     HMAC_SHA1_RESPONSE_SIZE,
@@ -59,6 +65,11 @@
     "derive_composite_key",
     "derive_key_aes_kdf",
     "derive_key_argon2",
+    # Keyfile
+    "KeyFileVersion",
+    "create_keyfile",
+    "create_keyfile_bytes",
+    "parse_keyfile",
     # YubiKey
     "HMAC_SHA1_RESPONSE_SIZE",
     "YUBIKEY_AVAILABLE",
diff --git a/src/kdbxtool/security/kdf.py b/src/kdbxtool/security/kdf.py
@@ -20,9 +20,9 @@
 from argon2.low_level import Type as Argon2Type
 from argon2.low_level import hash_secret_raw
 
-from kdbxtool.exceptions import InvalidKeyFileError, KdfError, MissingCredentialsError
+from kdbxtool.exceptions import KdfError, MissingCredentialsError
 
-from .crypto import constant_time_compare
+from .keyfile import parse_keyfile
 from .memory import SecureBytes
 
 if TYPE_CHECKING:
@@ -405,67 +405,6 @@ def derive_key_aes_kdf(
     return SecureBytes(derived)
 
 
-def _process_keyfile(keyfile_data: bytes) -> bytes:
-    """Process keyfile data according to KeePass keyfile format.
-
-    KeePass supports several keyfile formats:
-    1. XML keyfile (v1.0 or v2.0) - key is base64/hex encoded in XML
-    2. 32-byte raw binary - used directly
-    3. 64-byte hex string - decoded from hex
-    4. Any other size - SHA-256 hashed
-
-    Args:
-        keyfile_data: Raw keyfile contents
-
-    Returns:
-        32-byte key derived from keyfile
-    """
-    # Try parsing as XML keyfile
-    try:
-        import base64
-
-        import defusedxml.ElementTree as ET
-
-        tree = ET.fromstring(keyfile_data)
-        version_elem = tree.find("Meta/Version")
-        data_elem = tree.find("Key/Data")
-
-        if version_elem is not None and data_elem is not None:
-            version = version_elem.text or ""
-            if version.startswith("1.0"):
-                # Version 1.0: base64 encoded
-                return base64.b64decode(data_elem.text or "")
-            elif version.startswith("2.0"):
-                # Version 2.0: hex encoded with hash verification
-                key_hex = (data_elem.text or "").strip()
-                key_bytes = bytes.fromhex(key_hex)
-                # Verify hash if present (constant-time comparison)
-                if "Hash" in data_elem.attrib:
-                    expected_hash = bytes.fromhex(data_elem.attrib["Hash"])
-                    computed_hash = hashlib.sha256(key_bytes).digest()[:4]
-                    if not constant_time_compare(expected_hash, computed_hash):
-                        raise InvalidKeyFileError("Keyfile hash verification failed")
-                return key_bytes
-    except (ET.ParseError, ValueError, AttributeError):
-        pass  # Not an XML keyfile
-
-    # Check for raw 32-byte key
-    if len(keyfile_data) == 32:
-        return keyfile_data
-
-    # Check for 64-byte hex-encoded key
-    if len(keyfile_data) == 64:
-        try:
-            # Verify it's valid hex
-            int(keyfile_data, 16)
-            return bytes.fromhex(keyfile_data.decode("ascii"))
-        except (ValueError, UnicodeDecodeError):
-            pass  # Not hex
-
-    # Hash anything else
-    return hashlib.sha256(keyfile_data).digest()
-
-
 def derive_composite_key(
     password: str | None = None,
     keyfile_data: bytes | None = None,
@@ -513,7 +452,7 @@ def derive_composite_key(
             parts.append(pwd_hash.data)
 
         if keyfile_data is not None:
-            key_bytes = _process_keyfile(keyfile_data)
+            key_bytes = parse_keyfile(keyfile_data)
             parts.append(key_bytes)
 
         if yubikey_response is not None:
diff --git a/src/kdbxtool/security/keyfile.py b/src/kdbxtool/security/keyfile.py
@@ -0,0 +1,232 @@
+"""KeePass keyfile creation and parsing.
+
+This module provides support for all KeePass keyfile formats:
+- XML v2.0: Recommended format with hex-encoded key and SHA-256 hash verification
+- XML v1.0: Legacy format with base64-encoded key
+- RAW_32: Raw 32-byte binary key
+- HEX_64: 64-character hex string
+
+Example:
+    from kdbxtool import create_keyfile, KeyFileVersion
+
+    # Create recommended XML v2.0 keyfile
+    create_keyfile("my.keyx", version=KeyFileVersion.XML_V2)
+
+    # Create raw 32-byte keyfile
+    create_keyfile("my.key", version=KeyFileVersion.RAW_32)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from enum import StrEnum
+from pathlib import Path
+
+from kdbxtool.exceptions import InvalidKeyFileError
+
+from .crypto import constant_time_compare
+
+
+class KeyFileVersion(StrEnum):
+    """Supported KeePass keyfile formats.
+
+    Attributes:
+        XML_V2: XML format v2.0 with hex-encoded key and SHA-256 hash verification.
+            This is the recommended format for new keyfiles. Uses .keyx extension.
+        XML_V1: Legacy XML format v1.0 with base64-encoded key.
+            Supported for compatibility. Uses .key extension.
+        RAW_32: Raw 32-byte binary key. Simple but no integrity verification.
+        HEX_64: 64-character hex string (32 bytes encoded as hex).
+    """
+
+    XML_V2 = "xml_v2"
+    XML_V1 = "xml_v1"
+    RAW_32 = "raw_32"
+    HEX_64 = "hex_64"
+
+
+def create_keyfile_bytes(version: KeyFileVersion = KeyFileVersion.XML_V2) -> bytes:
+    """Create a new keyfile and return its contents as bytes.
+
+    Generates a cryptographically secure 32-byte random key and encodes it
+    in the specified format.
+
+    Args:
+        version: Keyfile format to use. Defaults to XML_V2 (recommended).
+
+    Returns:
+        Keyfile contents as bytes, ready to write to a file.
+
+    Example:
+        keyfile_data = create_keyfile_bytes(KeyFileVersion.XML_V2)
+        with open("my.keyx", "wb") as f:
+            f.write(keyfile_data)
+    """
+    # Generate 32 bytes of cryptographically secure random data
+    key_bytes = os.urandom(32)
+
+    if version == KeyFileVersion.XML_V2:
+        return _create_xml_v2(key_bytes)
+    elif version == KeyFileVersion.XML_V1:
+        return _create_xml_v1(key_bytes)
+    elif version == KeyFileVersion.RAW_32:
+        return key_bytes
+    elif version == KeyFileVersion.HEX_64:
+        return key_bytes.hex().encode("ascii")
+    else:
+        raise ValueError(f"Unknown keyfile version: {version}")
+
+
+def create_keyfile(
+    path: str | Path,
+    version: KeyFileVersion = KeyFileVersion.XML_V2,
+) -> None:
+    """Create a new keyfile at the specified path.
+
+    Generates a cryptographically secure 32-byte random key and saves it
+    in the specified format.
+
+    Args:
+        path: Path where the keyfile will be created.
+        version: Keyfile format to use. Defaults to XML_V2 (recommended).
+
+    Raises:
+        OSError: If the file cannot be written.
+
+    Example:
+        # Create XML v2.0 keyfile (recommended)
+        create_keyfile("vault.keyx")
+
+        # Create raw binary keyfile
+        create_keyfile("vault.key", version=KeyFileVersion.RAW_32)
+    """
+    keyfile_data = create_keyfile_bytes(version)
+    Path(path).write_bytes(keyfile_data)
+
+
+def parse_keyfile(keyfile_data: bytes) -> bytes:
+    """Parse keyfile data and extract the 32-byte key.
+
+    KeePass supports several keyfile formats:
+    1. XML keyfile (v1.0 or v2.0) - key is base64/hex encoded in XML
+    2. 32-byte raw binary - used directly
+    3. 64-byte hex string - decoded from hex
+    4. Any other size - SHA-256 hashed
+
+    Args:
+        keyfile_data: Raw keyfile contents.
+
+    Returns:
+        32-byte key derived from keyfile.
+
+    Raises:
+        InvalidKeyFileError: If keyfile format is invalid or hash verification fails.
+    """
+    # Try parsing as XML keyfile
+    try:
+        import base64
+
+        import defusedxml.ElementTree as ET
+
+        tree = ET.fromstring(keyfile_data)
+        version_elem = tree.find("Meta/Version")
+        data_elem = tree.find("Key/Data")
+
+        if version_elem is not None and data_elem is not None:
+            version = version_elem.text or ""
+            if version.startswith("1.0"):
+                # Version 1.0: base64 encoded
+                return base64.b64decode(data_elem.text or "")
+            elif version.startswith("2.0"):
+                # Version 2.0: hex encoded with hash verification
+                key_hex = (data_elem.text or "").strip()
+                key_bytes = bytes.fromhex(key_hex)
+                # Verify hash if present (constant-time comparison)
+                if "Hash" in data_elem.attrib:
+                    expected_hash = bytes.fromhex(data_elem.attrib["Hash"])
+                    computed_hash = hashlib.sha256(key_bytes).digest()[:4]
+                    if not constant_time_compare(expected_hash, computed_hash):
+                        raise InvalidKeyFileError("Keyfile hash verification failed")
+                return key_bytes
+    except (ET.ParseError, ValueError, AttributeError):
+        pass  # Not an XML keyfile
+
+    # Check for raw 32-byte key
+    if len(keyfile_data) == 32:
+        return keyfile_data
+
+    # Check for 64-byte hex-encoded key
+    if len(keyfile_data) == 64:
+        try:
+            # Verify it's valid hex
+            int(keyfile_data, 16)
+            return bytes.fromhex(keyfile_data.decode("ascii"))
+        except (ValueError, UnicodeDecodeError):
+            pass  # Not hex
+
+    # Hash anything else
+    return hashlib.sha256(keyfile_data).digest()
+
+
+def _create_xml_v2(key_bytes: bytes) -> bytes:
+    """Create XML v2.0 keyfile content.
+
+    Format:
+        <?xml version="1.0" encoding="utf-8"?>
+        <KeyFile>
+            <Meta>
+                <Version>2.0</Version>
+            </Meta>
+            <Key>
+                <Data Hash="XXXXXXXX">hex-encoded-key</Data>
+            </Key>
+        </KeyFile>
+
+    The Hash attribute contains the first 4 bytes of SHA-256(key) as hex.
+    """
+    key_hex = key_bytes.hex().upper()
+    hash_hex = hashlib.sha256(key_bytes).digest()[:4].hex().upper()
+
+    xml = f"""<?xml version="1.0" encoding="utf-8"?>
+<KeyFile>
+\t<Meta>
+\t\t<Version>2.0</Version>
+\t</Meta>
+\t<Key>
+\t\t<Data Hash="{hash_hex}">{key_hex}</Data>
+\t</Key>
+</KeyFile>
+"""
+    return xml.encode("utf-8")
+
+
+def _create_xml_v1(key_bytes: bytes) -> bytes:
+    """Create XML v1.0 keyfile content.
+
+    Format:
+        <?xml version="1.0" encoding="utf-8"?>
+        <KeyFile>
+            <Meta>
+                <Version>1.00</Version>
+            </Meta>
+            <Key>
+                <Data>base64-encoded-key</Data>
+            </Key>
+        </KeyFile>
+    """
+    import base64
+
+    key_b64 = base64.b64encode(key_bytes).decode("ascii")
+
+    xml = f"""<?xml version="1.0" encoding="utf-8"?>
+<KeyFile>
+\t<Meta>
+\t\t<Version>1.00</Version>
+\t</Meta>
+\t<Key>
+\t\t<Data>{key_b64}</Data>
+\t</Key>
+</KeyFile>
+"""
+    return xml.encode("utf-8")
diff --git a/tests/test_keyfile.py b/tests/test_keyfile.py
