Add keychain support for decrypting FortiGate firmware files (#1469)

Author: yunzheng

dissect/target/plugins/os/unix/linux/fortios/_os.py

@@ -13,6 +13,7 @@
 from dissect.util.compression import xz
 
 from dissect.target.filesystems.tar import TarFilesystem
+from dissect.target.helpers import keychain
 from dissect.target.helpers.fsutil import open_decompress
 from dissect.target.helpers.record import TargetRecordDescriptor, UnixUserRecord
 from dissect.target.plugin import OperatingSystem, export
@@ -117,9 +118,37 @@ def create(cls, target: Target, sysvol: Filesystem) -> Self:
             try:
                 kernel_hash = get_kernel_hash(sysvol)
                 target.log.info("Kernel hash: %s", kernel_hash)
-                key = key_iv_for_kernel_hash(kernel_hash)
-                target.log.info("Trying to decrypt_rootfs using key: %r", key)
-                rfs_fh = decrypt_rootfs(rootfs.open(), key)
+
+                keys: list[ChaCha20Key | AesKey] = []
+
+                # Loads known key from built-in map
+                try:
+                    keys.append(key_iv_for_kernel_hash(kernel_hash))
+                except ValueError:
+                    target.log.warning("No known decryption key for kernel hash (%s)", kernel_hash)
+
+                # Load keys from keychain
+                keychain_keys = key_iv_from_keychain(target, kernel_hash=kernel_hash)
+                keys.extend(keychain_keys)
+                target.log.warning("Found %d key(s) in keychain", len(keychain_keys))
+
+                if not keys:
+                    raise ValueError("No decryption keys available")  # noqa: TRY301
+
+                # Try to decrypt with all available keys
+                rfs_fh = None
+                for key in keys:
+                    target.log.warning("Trying to decrypt_rootfs using key: %r", key)
+                    try:
+                        rfs_fh = decrypt_rootfs(rootfs.open(), key)
+                        break
+                    except ValueError:
+                        target.log.info("Decryption with key %r failed", key)
+                        continue
+
+                if not rfs_fh:
+                    raise ValueError("All decryption attempts failed")  # noqa: TRY301
+
                 target.log.info("Decrypted fh: %r", rfs_fh)
                 vfs = create_tar_filesystem(rfs_fh)
             except RuntimeError:
@@ -528,6 +557,50 @@ def key_iv_for_kernel_hash(kernel_hash: str) -> AesKey | ChaCha20Key:
     raise ValueError(f"No known decryption keys for kernel hash: {kernel_hash}")
 
 
+def key_iv_from_keychain(target: Target, kernel_hash: str) -> list[ChaCha20Key | AesKey]:
+    """Return list of ChaCha20Key and AesKey from keychain.
+
+    When using the ``--keychain-file`` option, the CSV format is:
+
+        provider,key_type,identifier,value
+        fortios-chacha20seed,recovery_key,<kernel_hash>,<chacha20_seed>
+        fortios-chacha20key,recovery_key,<kernel_hash>,<chacha20_key>:<chacha20_iv>
+        fortios-aeskey,recovery_key,<kernel_hash>,<aes_key>:<aes_iv>
+
+    When using the ``--keychain-value`` option, multiple keys are returned due to missing provider.
+
+    Args:
+        target: Target instance.
+        kernel_hash: SHA256 hash of the kernel file used to match key identifiers in the keychain.
+
+    Returns:
+        List of ChaCha20Key or AesKey.
+    """
+    keys: list[ChaCha20Key | AesKey] = []
+    keychain_keys = keychain.get_all_keys()
+
+    # We prioritize keys with matching identifier (kernel hash)
+    identifier_keys = [key for key in keychain_keys if key.identifier == kernel_hash]
+    other_keys = [key for key in keychain_keys if key.identifier is None]
+
+    for key in identifier_keys + other_keys:
+        if not isinstance(key.value, str):
+            continue
+        if key.provider in ("fortios-chacha20seed", None) and len(key.value) == 64:
+            # 32 bytes hex string
+            key_data, key_iv = _kdf_7_4_x(key.value)
+            keys.append(ChaCha20Key(key_data, key_iv))
+        elif key.provider in ("fortios-aeskey", None) and len(key.value) == 97 and ":" in key.value:
+            # 48 bytes hex string with colon separator
+            key_data, _, key_iv = key.value.partition(":")
+            keys.append(AesKey(key_data, key_iv))
+        elif key.provider in ("fortios-chacha20key", None) and len(key.value) == 97 and ":" in key.value:
+            # 48 bytes hex string with colon separator
+            key_data, _, key_iv = key.value.partition(":")
+            keys.append(ChaCha20Key(key_data, key_iv))
+    return keys
+
+
 def chacha20_decrypt(fh: BinaryIO, key: ChaCha20Key) -> bytes:
     """Decrypt file using ChaCha20 with given ChaCha20Key.
 
@@ -636,7 +709,8 @@ def decrypt_rootfs(fh: BinaryIO, key: ChaCha20Key | AesKey) -> BinaryIO:
         result = chacha20_decrypt(fh, key)
     elif isinstance(key, AesKey):
         result = aes_decrypt(fh, key)
-        result = result[:-256]  # strip off the 256 byte footer
+        if len(result) > 256:
+            result = result[:-256]  # strip off the 256 byte footer
 
     if result[0:2] != b"\x1f\x8b":
         raise ValueError("Failed to decrypt: No gzip magic header found.")

tests/plugins/os/unix/linux/fortios/test_keys.py

@@ -2,9 +2,11 @@
 
 import re
 from io import BytesIO
+from typing import TYPE_CHECKING
 
 import pytest
 
+from dissect.target.helpers import keychain
 from dissect.target.plugins.os.unix.linux.fortios._keys import (
     KERNEL_KEY_MAP,
     AesKey,
@@ -15,8 +17,14 @@
     aes_decrypt,
     decrypt_rootfs,
     key_iv_for_kernel_hash,
+    key_iv_from_keychain,
 )
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from dissect.target.target import Target
+
 
 def test_kernel_key_map() -> None:
     # Ensure that the kernel key map is valid
@@ -84,3 +92,77 @@ def test_aes_decrypt() -> None:
     assert isinstance(key, AesKey)
     data = aes_decrypt(BytesIO(encrypted_rootfs_header), key)
     assert data == decrypted_rootfs_header
+
+
+def test_decrypt_rootfs_from_keychain_file(target_unix: Target, tmp_path: Path) -> None:
+    # encrypted FGT_1000D-v7.6.4.F-build3596-FORTINET.out/rootfs.gz
+    kernel_hash = "8e7fb3af9fe68d69af224857164347cee271264308c8ba86e9ad036e405ac6c8"
+    encrypted_rootfs_header = bytes.fromhex(
+        """
+    d739 ba66 6d65 ca64 4295 b7e4 3c48 7165
+    49ab e60c fc39 ef48 30b0 06cd f32c 37f2
+    """
+    )
+    decrypted_rootfs_header = bytes.fromhex(
+        """
+    1f8b 0800 4d07 a668 0003 a4d3 5390 2ed0
+    d226 e8c2 aeaf 6cdb b66d dbb6 6d57 edb2
+    """
+    )
+
+    keys = key_iv_from_keychain(target_unix, kernel_hash=kernel_hash)
+    assert not keys, "Keys found in keychain when none were expected"
+
+    keychain_file = tmp_path / "fortios_keychain.csv"
+    keychain_file.write_text(
+        "fortios-aeskey,recovery_key,"
+        "8e7fb3af9fe68d69af224857164347cee271264308c8ba86e9ad036e405ac6c8,"
+        "5adbbe614bcde31c3e05ba2e261c1a2410f0900ed340689835520a0612fc612b:e4973d6eff0412b4dbf4fe43c4d3136d"
+    )
+    keychain.register_keychain_file(keychain_file)
+
+    keys = key_iv_from_keychain(target_unix, kernel_hash=kernel_hash)
+    assert keys, "No keys found in keychain for testing"
+
+    for key in keys:
+        assert isinstance(key, AesKey)
+        assert key.key == bytes.fromhex("5adbbe614bcde31c3e05ba2e261c1a2410f0900ed340689835520a0612fc612b")
+        assert key.iv == bytes.fromhex("e4973d6eff0412b4dbf4fe43c4d3136d")
+
+        fh = decrypt_rootfs(BytesIO(encrypted_rootfs_header), key)
+        assert fh.read() == decrypted_rootfs_header
+
+
+def test_decrypt_rootfs_from_keychain_value(target_unix: Target) -> None:
+    # encrypted FGT_1000D-v7.6.4.F-build3596-FORTINET.out/rootfs.gz
+    kernel_hash = "8e7fb3af9fe68d69af224857164347cee271264308c8ba86e9ad036e405ac6c8"
+    encrypted_rootfs_header = bytes.fromhex(
+        """
+    d739 ba66 6d65 ca64 4295 b7e4 3c48 7165
+    49ab e60c fc39 ef48 30b0 06cd f32c 37f2
+    """
+    )
+    decrypted_rootfs_header = bytes.fromhex(
+        """
+    1f8b 0800 4d07 a668 0003 a4d3 5390 2ed0
+    d226 e8c2 aeaf 6cdb b66d dbb6 6d57 edb2
+    """
+    )
+
+    keys = key_iv_from_keychain(target_unix, kernel_hash=kernel_hash)
+    assert not keys, "Keys found in keychain when none were expected"
+
+    keychain.register_wildcard_value(
+        "5adbbe614bcde31c3e05ba2e261c1a2410f0900ed340689835520a0612fc612b:e4973d6eff0412b4dbf4fe43c4d3136d"
+    )
+
+    keys = key_iv_from_keychain(target_unix, kernel_hash=kernel_hash)
+    assert keys, "No keys found in keychain for testing"
+
+    for key in keys:
+        assert isinstance(key, AesKey)
+        assert key.key == bytes.fromhex("5adbbe614bcde31c3e05ba2e261c1a2410f0900ed340689835520a0612fc612b")
+        assert key.iv == bytes.fromhex("e4973d6eff0412b4dbf4fe43c4d3136d")
+
+        fh = decrypt_rootfs(BytesIO(encrypted_rootfs_header), key)
+        assert fh.read() == decrypted_rootfs_header