decbackup 0.1.0__py3-none-any.whl

decbackup/__init__.py

@@ -0,0 +1,10 @@
+"""decbackup — Python clone of the Stormshield SNS backup decryption utility.
+
+Reimplementation of ``/usr/Firewall/sbin/decbackup`` and the backup
+container handling of ``libncrypto.so`` from Stormshield SNS v5.1.4,
+derived by reverse engineering (see ``RECON.md``).
+"""
+
+__version__ = "0.1.0"
+
+from .backup import BackupError, decrypt_backup  # noqa: F401

decbackup/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

decbackup/backup.py

@@ -0,0 +1,238 @@
+"""Stormshield SNS backup container (``.bkup``) reader.
+
+Layout, recovered from ``libncrypto.so`` ``fwcrypto_upd_update`` (flags=2,
+the backup path) and cross-checked against ``encbackup``-produced files::
+
+    offset           size    contents
+    ------------------------------------------------------
+    0x000            0x400   ``[BACKUP]`` header, key=value lines,
+                             NUL terminated, zero padded to 0x400
+    0x400            4       be32 *X* — length of the PKCS#7 trailer
+    0x404            X       detached PKCS#7 SignedData (signature over
+                             the full header block + plaintext, device
+                             certificate, CA intermediate)
+    0x404+X          4       be32 *Y* — plaintext/ciphertext length
+    0x408+X          Y       AES-128-CBC ciphertext (PKCS#7 padding)
+
+The original processes the file in 0x4000-byte chunks and only verifies
+the signature when the trailer fits inside the first chunk; anything that
+does not fit is rejected fail-closed (error 6), so the clone can simply
+read the whole file.
+
+Error codes are those printed by ``decbackup``'s
+``decrypt and/or verify backup failed (%d)`` message; see RECON.md for the
+empirical derivation of each.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+from pathlib import Path
+
+from . import crypto, pkcs7, trust
+
+HEADER_LEN = 0x400
+CHUNK_LEN = 0x4000
+
+# Error codes as reported by the original tool.
+E_OK = 0
+E_FILE = 1  # input/output could not be opened
+E_PARSE = 6  # signature trailer / crypto parameters unparsable
+E_VERIFY = 7  # signature, chain or content digest verification failed
+E_HEADER = 8  # file shorter than the 0x400 header block
+E_MAJVERSION = 12  # unknown backup majversion / "Invalid archive"
+E_DECRYPT = 13  # decryption failed (in practice: wrong password)
+E_ALGO = 32  # unsupported cipher algorithm
+
+_INT_RE = re.compile(r"[0-9]{1,4}\Z")
+
+
+class BackupError(Exception):
+    """Decryption/verification failure carrying the original error code."""
+
+    def __init__(self, code: int, detail: str = ""):
+        super().__init__(f"({code}) {detail}" if detail else f"({code})")
+        self.code = code
+
+
+def parse_header(block: bytes) -> tuple[str, dict[str, str]]:
+    """Split the header block at its NUL and parse ``key=value`` lines.
+
+    Values may be double-quoted (``description="..."``).  Returns the raw
+    text and an ordered mapping of the parameters.
+    """
+    text = block.split(b"\x00", 1)[0].decode("latin-1")
+    fields: dict[str, str] = {}
+    for line in text.splitlines():
+        key, _, value = line.partition("=")
+        if not _:
+            continue
+        # values stay verbatim (the original's str_get_int_ex tolerates
+        # leading but not trailing whitespace, so keep it observable)
+        if len(value) >= 2 and value[0] == '"' == value[-1]:
+            value = value[1:-1]
+        fields[key.strip()] = value
+    return text, fields
+
+
+def _be32(buf: bytes, off: int) -> int:
+    return int.from_bytes(buf[off : off + 4], "big")
+
+
+def _version_ok(value: str | None) -> bool:
+    """The original gate at 0x1318e (``Invalid archive``).
+
+    ``fwcrypto_maj_get_version`` runs the parsed value through
+    ``str_get_int_ex``, which skips *leading* whitespace but fails on
+    trailing characters (strict mode).  Empirically a pure decimal value
+    of up to four digits is compared against 1 and anything else (dotted
+    versions, longer digit strings, trailing spaces) falls back to the
+    default of 1 and passes.  See RECON.md: probes ``version=9`` → 12,
+    ``version="9    "`` → 7 (accepted), ``version=90000`` → 7 (accepted),
+    ``version=5.1.4`` → accepted.
+    """
+    m = _INT_RE.match((value or "").lstrip())
+    return m is None or int(m.group()) == 1
+
+
+def _crypto_datas(fields: dict[str, str], maj_v: int, password: str) -> tuple[bytes, bytes, int]:
+    """``fwcrypto_get_backup_crypto_datas`` + key derivation."""
+    algo = int(fields["algo"]) if fields.get("algo", "").isdigit() else None
+    if maj_v == 2:
+        if algo is None:
+            raise BackupError(E_PARSE, "missing algo")
+        try:
+            salt = bytes.fromhex(fields["salt"])
+            iv = bytes.fromhex(fields["iv"])
+        except (KeyError, ValueError) as exc:
+            raise BackupError(E_PARSE, f"bad salt/iv: {exc}") from exc
+        iterations = fields.get("pbkdf_iterations", "1")
+        if not iterations.isdigit():
+            raise BackupError(E_PARSE, "bad pbkdf_iterations")
+        key = crypto.derive_key_v2(password.encode(), salt, int(iterations))
+    else:  # v1: salted SHA1, no parameters in the header
+        if algo is None:
+            algo = crypto.ALGO_AES_128_CBC
+        pwd = password.encode()
+        key = crypto.derive_key_v1(pwd)
+        iv = crypto.derive_iv_v1(pwd)
+    return key, iv, algo
+
+
+def decrypt_backup(
+    input_path: str | os.PathLike,
+    output_path: str | os.PathLike,
+    password: str = "",
+    *,
+    verify: bool = True,
+) -> dict[str, str]:
+    """Decrypt and (by default) verify a backup, mirroring ``decbackup``.
+
+    Returns the parsed header fields on success; raises :class:`BackupError`
+    with the original's numeric code otherwise.  No output file survives a
+    failure — the original deletes it on every error path.
+
+    ``verify=False`` is a clone extension (no such option exists on the
+    device): it skips PKCS#7 trailer parsing and chain/signature
+    verification entirely — the trailer length field is still required to
+    locate the payload.  The output is then UNAUTHENTICATED plaintext;
+    successful decryption alone says nothing about origin or integrity.
+    """
+    out = Path(output_path)
+    try:
+        # The original fopen()s the output early ("wb", truncating any
+        # existing file) and removes it again on every error path.
+        out.write_bytes(b"")
+        return _decrypt_backup(input_path, out, password, verify)
+    except BackupError:
+        with contextlib.suppress(OSError):
+            out.unlink(missing_ok=True)
+        raise
+    except OSError as exc:
+        raise BackupError(E_FILE, str(exc)) from exc
+
+
+def _decrypt_backup(input_path, out: Path, password: str, verify: bool = True) -> dict[str, str]:
+    try:
+        data = Path(input_path).read_bytes()
+    except OSError as exc:
+        raise BackupError(E_FILE, str(exc)) from exc
+
+    if len(data) < HEADER_LEN:
+        raise BackupError(E_HEADER, "file shorter than backup header")
+
+    block = data[:HEADER_LEN]
+    _text, fields = parse_header(block)
+
+    # Empirically the version gate fires before the trailer-fit check:
+    # a length-shifted file with a bad version yields 12, not 6 (§6).
+    if not _version_ok(fields.get("version")):
+        raise BackupError(E_MAJVERSION, "Invalid archive")
+
+    # The signature trailer must fit in the first 0x4000-byte chunk the
+    # original reads; otherwise verification can never run and the file
+    # is rejected fail-closed (fwcrypto_upd_get_signature failed).
+    first_len = min(CHUNK_LEN, len(data))
+    sig_len = _be32(data, HEADER_LEN)
+    if sig_len + HEADER_LEN + 4 >= first_len:
+        raise BackupError(E_PARSE, "fwcrypto_upd_get_signature failed")
+
+    # fwcrypto_get_backup_majversion: defaults to 1 when the key is absent.
+    maj = fields.get("majversion")
+    if maj is None:
+        maj_v = 1
+    elif re.fullmatch(r"[0-9]+", maj):
+        maj_v = int(maj)
+    else:
+        maj_v = 1
+    if maj_v not in (1, 2):
+        raise BackupError(E_MAJVERSION, f"Unknown backup majversion: {maj_v}")
+
+    if verify:
+        try:
+            certs, signers = pkcs7.parse_signed_data(
+                data[HEADER_LEN + 4 : HEADER_LEN + 4 + sig_len]
+            )
+        except pkcs7.SignatureError as exc:
+            # fail closed: unparsable trailer means no verification possible
+            raise BackupError(E_PARSE, str(exc)) from exc
+
+    try:
+        key, iv, algo = _crypto_datas(fields, maj_v, password)
+    except BackupError:
+        raise
+    except (ValueError, KeyError) as exc:
+        raise BackupError(E_PARSE, f"fwcrypto_get_backup_crypto_datas: {exc}") from exc
+
+    if algo != crypto.ALGO_AES_128_CBC:
+        raise BackupError(E_ALGO, f"unsupported algo ({algo})")
+
+    off = HEADER_LEN + 4 + sig_len + 4
+    if off >= len(data):
+        raise BackupError(E_PARSE, "fwcrypto_upd_get_data_size failed")
+    # The device decrypts filesize - off bytes and ignores the be32 Y
+    # field (device probes: +16 trailing bytes -> 13; 16 bytes short -> 13).
+    ciphertext = data[off:]
+    if len(ciphertext) % 16:
+        raise BackupError(E_DECRYPT, "EVP_CipherFinal (maj) failed")
+
+    try:
+        plaintext = crypto.pkcs7_unpad(crypto.aes_cbc_decrypt(key, iv, ciphertext))
+    except ValueError as exc:
+        raise BackupError(E_DECRYPT, f"decrypt failed: {exc}") from exc
+
+    if verify:
+        content = block + plaintext
+        try:
+            signer_der = signers[0].verify(certs, content)
+            trust.verify_chain(signer_der, certs)
+        except (pkcs7.SignatureError, trust.ChainError) as exc:
+            raise BackupError(E_VERIFY, f"invalid backup: {exc}") from exc
+
+    try:
+        out.write_bytes(plaintext)
+    except OSError as exc:
+        raise BackupError(E_FILE, str(exc)) from exc
+    return fields

decbackup/cli.py

@@ -0,0 +1,110 @@
+"""Command line interface, mirroring ``/usr/Firewall/sbin/decbackup``.
+
+getopt string ``Pi:p:o:d``.  Success is silent (exit 0); failure prints
+``decrypt and/or verify backup failed (%d)`` and exits 1.  ``-d`` dumps
+the backup header after a successful decryption.
+"""
+
+from __future__ import annotations
+
+import getopt
+import sys
+
+from .backup import HEADER_LEN, BackupError, decrypt_backup
+
+USAGE = (
+    "Usage : () -i <backup> -o <output archive>\n"
+    "                    [-p <password>] [-d : dump backup header]\n"
+    "                    [-P : prompt for password]\n"
+    "                    [--no-verify : skip signature verification"
+    " (clone extension)]\n"
+)
+
+PROMPT = "Enter backup password (<Enter> for none): "
+
+
+def _read_password(prompt: bool) -> str:
+    """``t_getpass``: reads from /dev/tty; without a tty the password is
+    empty (empirically ``-P`` over a pipe yields error 13, i.e. an empty
+    password was used)."""
+    if not prompt and not sys.stdin.isatty():
+        return ""
+    try:
+        with open("/dev/tty", "r+") as tty:
+            tty.write(PROMPT)
+            tty.flush()
+            return tty.readline().rstrip("\r\n")
+    except OSError:
+        return ""
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    input_path = output_path = None
+    password: str | None = None
+    prompt = False
+    dump = False
+    verify = True
+    p_count = 0
+
+    # the original getopt string is exactly "Pi:p:o:d"; --no-verify is a
+    # long-option extension, which cannot collide with that grammar
+    try:
+        opts, _ = getopt.getopt(argv, "Pi:p:o:d", ["no-verify"])
+    except getopt.GetoptError as exc:
+        # match the C library's message shape
+        if exc.opt:
+            print(f"decbackup: illegal option -- {exc.opt}", file=sys.stderr)
+        else:
+            print(f"decbackup: {exc.msg}", file=sys.stderr)
+        print(USAGE, file=sys.stderr, end="")
+        return 1
+
+    for opt, arg in opts:
+        if opt == "-P":
+            prompt = True
+        elif opt == "-p":
+            p_count += 1
+            if p_count > 1:
+                # device-verified: message only, no usage dump
+                print("-p can only be specified once", file=sys.stderr)
+                return 1
+            password = arg
+        elif opt == "-i":
+            input_path = arg
+        elif opt == "-o":
+            output_path = arg
+        elif opt == "-d":
+            dump = True
+        elif opt == "--no-verify":
+            verify = False
+
+    if input_path is None or output_path is None:
+        print(USAGE, file=sys.stderr, end="")
+        return 1
+
+    if password is None:
+        password = _read_password(prompt)
+
+    if not verify:
+        print(
+            "decbackup: WARNING: signature verification skipped -- "
+            "the output is decrypted but UNAUTHENTICATED",
+            file=sys.stderr,
+        )
+
+    try:
+        decrypt_backup(input_path, output_path, password, verify=verify)
+    except BackupError as exc:
+        print(f"decrypt and/or verify backup failed ({exc.code})", file=sys.stderr)
+        return 1
+
+    if dump:
+        try:
+            with open(input_path, "rb") as f:
+                block = f.read(HEADER_LEN)
+        except OSError:
+            block = b""
+        text = block.split(b"\x00", 1)[0].decode("latin-1")
+        print(f"Header :\n{text}\n", end="")
+    return 0

decbackup/crypto.py

@@ -0,0 +1,82 @@
+"""Key derivation and ciphers recovered from ``libncrypto.so``.
+
+Two password-based schemes exist, selected by the backup header's
+``majversion`` field:
+
+* **v1** (``fwcrypto_keyfrompasswd`` / ``fwcrypto_ivfrompasswd``):
+  ``SHA1(salt_constant || password)``, truncated/padded to the wanted
+  length.  Only reachable by reading old backups; the 5.1.4 tools always
+  write v2.
+* **v2** (``fwcrypto_derivekey``): PBKDF2-HMAC-SHA256 over the password
+  with the header's ``salt``/``pbkdf_iterations``; the IV is stored in the
+  header in hex.
+
+Both feed AES-128-CBC (``algo=1``) with standard PKCS#7 padding.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+#: AES-128-CBC
+ALGO_AES_128_CBC = 1
+
+#: salt constants embedded in libncrypto.so .rodata at 0x1b41f / 0x1b40f
+V1_KEY_SALT = bytes.fromhex("2807a5ef00620c4b62f32e0985e30e4e")
+V1_IV_SALT = bytes.fromhex("463538798d48c8c0323df3e75109d221")
+
+#: key length actually requested by the backup path (``mov esi, 0x10``)
+KEY_LEN = 16
+
+
+def _sha1_salted(salt: bytes, password: bytes, size: int) -> bytes:
+    """``fwcrypto_keyfrompasswd``/``ivfrompasswd`` body.
+
+    ``SHA1(salt || password)``; when the requested size exceeds the 20-byte
+    digest the tail is filled with a byte progression (only relevant for
+    key sizes > 20, which the backup path never requests).
+    """
+    digest = hashlib.sha1(salt + password).digest()
+    if size <= len(digest):
+        return digest[:size]
+    buf = bytearray(digest) + bytes(size - len(digest))
+    for i in range(len(digest), size):
+        buf[i] = (size - 1 + (size - i) * 0xEB) & 0xFF
+    return bytes(buf)
+
+
+def derive_key_v1(password: bytes, size: int = KEY_LEN) -> bytes:
+    return _sha1_salted(V1_KEY_SALT, password, size)
+
+
+def derive_iv_v1(password: bytes, size: int = KEY_LEN) -> bytes:
+    return _sha1_salted(V1_IV_SALT, password, size)
+
+
+def derive_key_v2(password: bytes, salt: bytes, iterations: int, size: int = KEY_LEN) -> bytes:
+    return hashlib.pbkdf2_hmac("sha256", password, salt, iterations, size)
+
+
+def aes_cbc_decrypt(key: bytes, iv: bytes, data: bytes) -> bytes:
+    if len(data) % 16:
+        raise ValueError("ciphertext is not a multiple of the AES block size")
+    dec = Cipher(algorithms.AES(key), modes.CBC(iv)).decryptor()
+    return dec.update(data) + dec.finalize()
+
+
+def pkcs7_unpad(data: bytes) -> bytes:
+    """Strip PKCS#7 padding; raises ``ValueError`` on malformed padding.
+
+    Mirrors OpenSSL's ``EVP_CipherFinal`` behaviour: a bad padding check is
+    what makes a wrong password surface as error code 13.
+    """
+    if not data:
+        raise ValueError("empty plaintext")
+    pad = data[-1]
+    if not 1 <= pad <= 16 or len(data) < pad:
+        raise ValueError("bad PKCS#7 padding")
+    if data[-pad:] != bytes([pad]) * pad:
+        raise ValueError("bad PKCS#7 padding")
+    return data[:-pad]

decbackup/der.py

@@ -0,0 +1,77 @@
+"""Minimal DER (ASN.1 TLV) reader.
+
+Just enough to walk PKCS#7 SignedData structures. Every function works on
+plain ``bytes`` and offsets; a TLV is described by the tuple
+``(tag, value_start, length, next)`` where ``next == value_start + length``.
+"""
+
+from __future__ import annotations
+
+
+class DERError(ValueError):
+    """Raised when a buffer is not well-formed DER."""
+
+
+def read_tlv(buf: bytes, i: int) -> tuple[int, int, int, int]:
+    """Read one TLV at offset *i*; return ``(tag, value_start, length, next)``."""
+    try:
+        tag = buf[i]
+        j = i + 1
+        if tag == 0x00:  # padding
+            raise DERError("null filler")
+        if tag == 0xFF:
+            raise DERError("bad tag")
+        if tag & 0x1F == 0x1F:  # high tag number form
+            while buf[j] & 0x80:
+                j += 1
+            j += 1
+        first = buf[j]
+        j += 1
+        if first < 0x80:
+            length = first
+        elif first == 0x80:
+            raise DERError("indefinite length not supported")
+        else:
+            nbytes = first & 0x7F
+            if nbytes > 8:
+                raise DERError("overlong length")
+            length = int.from_bytes(buf[j : j + nbytes], "big")
+            j += nbytes
+        if j + length > len(buf):
+            raise DERError("truncated value")
+        return tag, j, length, j + length
+    except IndexError as exc:
+        raise DERError("truncated TLV") from exc
+
+
+def children(buf: bytes, start: int, end: int):
+    """Yield every TLV between *start* and *end* as
+    ``(tag, value_start, length, next)`` tuples."""
+    i = start
+    while i < end:
+        tlv = read_tlv(buf, i)
+        yield tlv
+        i = tlv[3]
+
+
+def encode_len(length: int) -> bytes:
+    """DER length encoding of an integer."""
+    if length < 0x80:
+        return bytes([length])
+    body = length.to_bytes((length.bit_length() + 7) // 8, "big")
+    return bytes([0x80 | len(body)]) + body
+
+
+def oid_str(buf: bytes, start: int, end: int) -> str:
+    """Decode an OBJECT IDENTIFIER value to dotted form."""
+    if start >= end:
+        return ""
+    first = buf[start]
+    parts = [str(first // 40), str(first % 40)]
+    value = 0
+    for byte in buf[start + 1 : end]:
+        value = (value << 7) | (byte & 0x7F)
+        if not byte & 0x80:
+            parts.append(str(value))
+            value = 0
+    return ".".join(parts)