decbackup 0.1.0__tar.gz → 0.2.0__tar.gz

decbackup-0.2.0/MANIFEST.in

@@ -0,0 +1,5 @@
+# The sdist must carry the runnable test suite promised in the README:
+# tests/test_decbackup.py alone is useless without the binary device vectors.
+graft tests
+include LICENSE
+include RECON.md

{decbackup-0.1.0 → decbackup-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: decbackup
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python clone of Stormshield SNS's decbackup: decrypt and verify .bkup appliance backups without the device
 Author: fl0l0u
 License-Expression: Apache-2.0
@@ -14,6 +14,11 @@ Classifier: Environment :: Console
 Classifier: Intended Audience :: System Administrators
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Security :: Cryptography
 Classifier: Topic :: System :: Archiving
 Requires-Python: >=3.9
@@ -52,6 +57,7 @@ Dynamic: license-file
   <a href="#usage">Usage</a> •
   <a href="#the-format">The Format</a> •
   <a href="#development">Development</a> •
+  <a href="#releasing">Releasing</a> •
   <a href="#license">License</a>
 </p>
 
@@ -70,10 +76,14 @@ plus an empirical error-code matrix against a live device (see
 |---------|-------------|
 | **Byte-exact format support** | `[BACKUP]` header, detached PKCS#7 trailer, AES-128-CBC payload |
 | **Both password schemes** | v2 (PBKDF2-HMAC-SHA256) and legacy v1 (salted-SHA1) key derivation |
-| **Full signature verification** | RSA over PKCS#7 authAttrs, messageDigest over header+payload, chain to the four CAs embedded in libncrypto, policy 1.3.6.1.4.1.11256.2.3, dates ignored (as on the device) |
+| **Full signature verification** | RSA over PKCS#7 authAttrs, messageDigest over header+payload, chain to the four CA certificates embedded in libncrypto, policy 1.3.6.1.4.1.11256.2.3, dates ignored (as on the device) |
 | **Original CLI parity** | same flags (`-i -o -p -P -d`), same messages, same numeric error codes (0/1/6/7/8/12/13/32) — validated against the real binary on device |
 | **Tiny dependency set** | `cryptography` only; DER/PKCS#7 parsing is in-tree (`decbackup/der.py`, `pkcs7.py`) |
 
+About the v1 row: no released SNS version emits the legacy v1 scheme (both
+tested `encbackup` builds write v2), so the v1 path is validated only
+through failure-path vectors, not a decryptable v1 backup.
+
 ## Installation
 
 ```bash
@@ -109,6 +119,10 @@ Success is silent (exit 0), exactly like the original; failure prints
 `decrypt and/or verify backup failed (%d)` with the appliance's own error
 code. `-d` prints the decoded header block after a successful run.
 
+Output-file contract (same as the device): the `-o` file is created and
+truncated early, and **deleted on every failure path** — a pre-existing
+file at `-o` is destroyed even when the backup is rejected.
+
 `--no-verify` has no counterpart on the device: it skips trailer
 parsing and signature/chain checks to rescue backups whose signature
 region is corrupted. It prints a warning and the output is
@@ -132,10 +146,14 @@ except BackupError as e:
 0x000   0x400   [BACKUP] key=value header, NUL-terminated, zero-padded
 0x400   4       be32 X — PKCS#7 trailer length
 0x404   X       detached PKCS#7 SignedData (device cert + CA intermediate)
-0x404+X 4       be32 Y — payload length
-0x408+X Y       AES-128-CBC ciphertext (PBKDF2-SHA256 key, PKCS#7 padding)
+0x404+X 4       be32 Y — ciphertext length
+0x408+X Y       AES-128-CBC ciphertext (PBKDF2-SHA256 key¹, PKCS#7 padding)
 ```
 
+¹ v2 key derivation; the legacy v1 scheme instead uses a salted-SHA1
+derivation (see [RECON.md](RECON.md)). Y counts ciphertext bytes including
+the padding, so it exceeds the plaintext by a partial or full AES block.
+
 The signature covers the **full 0x400-byte header block plus the decrypted
 payload**; it chains device cert → *Stormshield Network Security Products
 CA* → *Stormshield Products Root CA* (embedded). Expired device
@@ -148,13 +166,19 @@ readable forever. Full details in [RECON.md](RECON.md).
 decbackup/        the package (cli, backup format, crypto, pkcs7, der, trust, certs/)
 analysis/         RE tooling: disassembler, strings, symbol lists, the device
                   extraction script and the empirical error-code matrix
-tests/vectors/    real encbackup-produced backups + expected payloads
-                  (created on an SNS 5.1.4 device, cross-validated against
-                  the stock decbackup)
+tests/vectors/    device-derived containers + expected payloads:
+                  test/nopass/big/mid are stock encbackup output from an
+                  SNS 5.1.4 device (cross-validated against the stock
+                  decbackup); v1probe/v1badkey are patched v4.2.8
+                  containers; extdup/lazyparse are pinned fuzz-crash
+                  mutations; trunc/xzero/ct/cert/mv3/v9/yt/ys/mvx are
+                  byte-edited probes
 legacy/           the earlier single-file iteration (kept for reference)
 ```
 
 ```bash
+pip install -e ".[dev]"               # dev extras: ruff
+ruff check .                          # lint (same as CI)
 python tests/test_decbackup.py        # exit code = number of failures
 python analysis/probes.py             # real-vs-clone error-code parity table
 python analysis/fuzz.py 30000         # robustness contract fuzzer
@@ -163,9 +187,10 @@ python analysis/fuzz.py 30000         # robustness contract fuzzer
 ## Releasing
 
 Tagged pushes (`v*`) build an sdist + wheel, smoke-test the wheel against
-the bundled device vectors, and publish to PyPI via trusted publishing
-(see `.github/workflows/release.yml`). Pushes and PRs run lint + the
-error-code parity suite on Python 3.9–3.13
+one bundled vector (`test.bkup`: clean decrypt, plus the wrong-password
+failure contract), and publish to PyPI via trusted publishing
+(see `.github/workflows/release.yml`). Pushes to `master`/`main` and pull
+requests run lint + the error-code parity suite on Python 3.9–3.13
 (`.github/workflows/ci.yml`).
 
 ```bash

{decbackup-0.1.0 → decbackup-0.2.0}/README.md

@@ -26,6 +26,7 @@
   <a href="#usage">Usage</a> •
   <a href="#the-format">The Format</a> •
   <a href="#development">Development</a> •
+  <a href="#releasing">Releasing</a> •
   <a href="#license">License</a>
 </p>
 
@@ -44,10 +45,14 @@ plus an empirical error-code matrix against a live device (see
 |---------|-------------|
 | **Byte-exact format support** | `[BACKUP]` header, detached PKCS#7 trailer, AES-128-CBC payload |
 | **Both password schemes** | v2 (PBKDF2-HMAC-SHA256) and legacy v1 (salted-SHA1) key derivation |
-| **Full signature verification** | RSA over PKCS#7 authAttrs, messageDigest over header+payload, chain to the four CAs embedded in libncrypto, policy 1.3.6.1.4.1.11256.2.3, dates ignored (as on the device) |
+| **Full signature verification** | RSA over PKCS#7 authAttrs, messageDigest over header+payload, chain to the four CA certificates embedded in libncrypto, policy 1.3.6.1.4.1.11256.2.3, dates ignored (as on the device) |
 | **Original CLI parity** | same flags (`-i -o -p -P -d`), same messages, same numeric error codes (0/1/6/7/8/12/13/32) — validated against the real binary on device |
 | **Tiny dependency set** | `cryptography` only; DER/PKCS#7 parsing is in-tree (`decbackup/der.py`, `pkcs7.py`) |
 
+About the v1 row: no released SNS version emits the legacy v1 scheme (both
+tested `encbackup` builds write v2), so the v1 path is validated only
+through failure-path vectors, not a decryptable v1 backup.
+
 ## Installation
 
 ```bash
@@ -83,6 +88,10 @@ Success is silent (exit 0), exactly like the original; failure prints
 `decrypt and/or verify backup failed (%d)` with the appliance's own error
 code. `-d` prints the decoded header block after a successful run.
 
+Output-file contract (same as the device): the `-o` file is created and
+truncated early, and **deleted on every failure path** — a pre-existing
+file at `-o` is destroyed even when the backup is rejected.
+
 `--no-verify` has no counterpart on the device: it skips trailer
 parsing and signature/chain checks to rescue backups whose signature
 region is corrupted. It prints a warning and the output is
@@ -106,10 +115,14 @@ except BackupError as e:
 0x000   0x400   [BACKUP] key=value header, NUL-terminated, zero-padded
 0x400   4       be32 X — PKCS#7 trailer length
 0x404   X       detached PKCS#7 SignedData (device cert + CA intermediate)
-0x404+X 4       be32 Y — payload length
-0x408+X Y       AES-128-CBC ciphertext (PBKDF2-SHA256 key, PKCS#7 padding)
+0x404+X 4       be32 Y — ciphertext length
+0x408+X Y       AES-128-CBC ciphertext (PBKDF2-SHA256 key¹, PKCS#7 padding)
 ```
 
+¹ v2 key derivation; the legacy v1 scheme instead uses a salted-SHA1
+derivation (see [RECON.md](RECON.md)). Y counts ciphertext bytes including
+the padding, so it exceeds the plaintext by a partial or full AES block.
+
 The signature covers the **full 0x400-byte header block plus the decrypted
 payload**; it chains device cert → *Stormshield Network Security Products
 CA* → *Stormshield Products Root CA* (embedded). Expired device
@@ -122,13 +135,19 @@ readable forever. Full details in [RECON.md](RECON.md).
 decbackup/        the package (cli, backup format, crypto, pkcs7, der, trust, certs/)
 analysis/         RE tooling: disassembler, strings, symbol lists, the device
                   extraction script and the empirical error-code matrix
-tests/vectors/    real encbackup-produced backups + expected payloads
-                  (created on an SNS 5.1.4 device, cross-validated against
-                  the stock decbackup)
+tests/vectors/    device-derived containers + expected payloads:
+                  test/nopass/big/mid are stock encbackup output from an
+                  SNS 5.1.4 device (cross-validated against the stock
+                  decbackup); v1probe/v1badkey are patched v4.2.8
+                  containers; extdup/lazyparse are pinned fuzz-crash
+                  mutations; trunc/xzero/ct/cert/mv3/v9/yt/ys/mvx are
+                  byte-edited probes
 legacy/           the earlier single-file iteration (kept for reference)
 ```
 
 ```bash
+pip install -e ".[dev]"               # dev extras: ruff
+ruff check .                          # lint (same as CI)
 python tests/test_decbackup.py        # exit code = number of failures
 python analysis/probes.py             # real-vs-clone error-code parity table
 python analysis/fuzz.py 30000         # robustness contract fuzzer
@@ -137,9 +156,10 @@ python analysis/fuzz.py 30000         # robustness contract fuzzer
 ## Releasing
 
 Tagged pushes (`v*`) build an sdist + wheel, smoke-test the wheel against
-the bundled device vectors, and publish to PyPI via trusted publishing
-(see `.github/workflows/release.yml`). Pushes and PRs run lint + the
-error-code parity suite on Python 3.9–3.13
+one bundled vector (`test.bkup`: clean decrypt, plus the wrong-password
+failure contract), and publish to PyPI via trusted publishing
+(see `.github/workflows/release.yml`). Pushes to `master`/`main` and pull
+requests run lint + the error-code parity suite on Python 3.9–3.13
 (`.github/workflows/ci.yml`).
 
 ```bash

decbackup-0.2.0/RECON.md

@@ -0,0 +1,386 @@
+# decbackup / Stormshield SNS backup Reverse-Engineering Recon
+
+Target: `/usr/Firewall/sbin/decbackup` + `libncrypto.so` from **Stormshield
+Network Security v5.1.4** (SNS-BSD 5.1.4, EVA1 XL-VM). All addresses below
+are file offsets into the binaries extracted from the device; those
+artifacts are **not in this repo** (the extraction workflow is §1), so
+resolve an address only against your own extracted copy.
+
+## 1. Environment & extraction workflow
+
+* SNS **v5.1.4** lab VM; admin shell is a **restricted csh whitelist**:
+  no `cat`, `od`, `printf`, `for`, no `2>` redirection (csh: `2>&1` =
+  "Ambiguous output redirect"). `ls`, `stat`, `sed`, `dd`, `bsdtar`,
+  `openssl`, `md5`, `encbackup`, `decbackup` *are* available.
+* SCP/SFTP is blocked. Files exfiltrate via
+  `ssh admin@vm 'openssl base64 -in /path/file' | base64 -d`
+  (`analysis/extract.sh`). Integrity confirmed with `md5` on both ends.
+* Analysis tooling: `analysis/disasm.py` (capstone + pyelftools function
+  disassembler with PLT-resolved call targets and string annotations),
+  `analysis/strings.py`, `analysis/symbols.py`.
+
+### Binaries that matter
+
+| file | role |
+|---|---|
+| `sbin/decbackup` | CLI front-end: getopt, password handling, `-d` dump |
+| `sbin/encbackup` | creates backups (`-i archive -o bkup -t all -p pass`) |
+| `sbin/backuprestore`, `sbin/backupinfo` | other consumers of the format |
+| `lib/libncrypto.so` | the whole format: `fwcrypto_upd_*`, KDF, PKCS#7 |
+| `lib/libnbase.so` | section/key-value parser (`str_get_int_ex` etc.) |
+
+## 2. Container format (CONFIRMED, byte-exact)
+
+```
+offset        size     contents
+0x000         0x400    [BACKUP] header: key=value lines, NUL-terminated,
+                       zero-padded to 1 KiB
+0x400         4        be32 X — length of the PKCS#7 trailer
+0x404         X        detached PKCS#7 SignedData (signature + certs)
+0x404+X       4        be32 Y — ciphertext length (== filesize - 0x408 - X)
+0x408+X       Y        AES-128-CBC ciphertext, PKCS#7 padding
+```
+
+Y counts the **encrypted** span, PKCS#7 padding included (measured:
+`test.bkup` Y=2064 over a 2048-byte plaintext). The parser does **not
+trust** it — decryption is bounded by filesize (yt/ys probes, §6).
+
+Header keys seen: `majversion=2`, `algo=1`, `date="…"`, `model`, `version`,
+`serial`, `advanced`, `description`, `content`, `iv` (hex), `salt` (hex),
+`pbkdf_iterations=10000`, `type=PASSWORD`, `validated`, `IPv6State`.
+Values may be double-quoted; the text block ends at the first NUL.
+
+Parsing path: `fwcrypto_upd_update` (libncrypto 0x12860, flags=2 backup
+path). The file is read in **0x4000-byte chunks**; the signature trailer
+must fit inside the first chunk (`X + 0x404 >= chunk_len → error 6`,
+`fwcrypto_upd_get_signature failed`) — a fail-closed design, so whole-file
+processing is behaviourally equivalent.
+
+**Quirk (not reproduced):** if the filesize is an exact multiple of
+0x4000, the streaming loop's EOF detection hits the zero-length-read path
+and the tool fails. A bug; the clone simply reads the whole file.
+
+## 3. Key derivation (CONFIRMED v2 and v1)
+
+Selected by header `majversion` (`fwcrypto_get_backup_majversion`,
+default 1 when the key is absent; 1 or 2 accepted, anything else → error 12
+`Unknown backup majversion`). "Anything else" applies to *parsed* numbers
+only: an unparsable value falls back to the default 1 exactly like an
+absent key (mvx probe, §6).
+
+* **v2** (`fwcrypto_derivekey`): `key = PBKDF2-HMAC-SHA256(password,
+  unhex(salt), pbkdf_iterations, 16)`; `iv = unhex(iv)`.
+* **v1**: `key = SHA1(2807a5ef00620c4b62f32e0985e30e4e || password)[:16]`,
+  `iv = SHA1(463538798d48c8c0323df3e75109d221 || password)[:16]`. The two
+  salts are consecutive 16-byte windows of one 48-byte pool
+  (`463538798d…09d221` + `2807a5ef00…0e4e`); the getters' `lea` targets
+  resolve to pool+0 and pool+16 in *both* the 5.1.4 and 4.2.8 binaries.
+  An earlier reading (`212807a5…` / `0046353879…`) was a one-byte
+  vaddr→file-offset slip, corrected in §12 by direct experiment.
+  For sizes >20 the fill is
+  `buf[i] = (size-1 + (size-i)*0xEB) & 0xFF` — unreachable for AES-128.
+  5.1.4 `encbackup` cannot emit v1 (no version flag in getopt
+  `i:o:p:c:t:n:P`), but the **key derivation is now empirically confirmed**
+  (§12): a v1-header archive whose ciphertext was made with these
+  constants decrypts cleanly on both VMs (reaches the digest check → 7),
+  while the shifted-salt variant fails at padding (→ 13) on both.
+
+Cipher: `algo=1` → AES-128-CBC (`EVP_aes_128_cbc`); anything else → error
+32 `unsupported algo`.
+
+## 4. Signature scheme (CONFIRMED end-to-end)
+
+Detached PKCS#7 SignedData (OpenSSL 3 `PKCS7_*` via
+`VerifyMajSignatureInit` 0x14a5? / `VerifySignatureFinal`; last nibble
+unresolved from notes):
+
+* **Signed content** = full 0x400-byte header block (text + NUL padding —
+  implemented as `strlen` + zero-pad loop) **followed by the decrypted
+  payload**. Proven: `messageDigest` attribute ==
+  `sha256(header_block + plaintext)` on every vector.
+* The trailer's SignedData quirks:
+  * certificates sit under `[0]` as bare `SEQUENCE` TLVs (no SET wrapper);
+  * `signerInfos` is a plain `0x31` SET;
+  * authenticatedAttributes are stored bare under the `[0]` tag — the
+    signed DER is the tag-swapped form `0x31 + DER-length + value`
+    (Stormshield's encoder omits the SET, so the length must be re-encoded;
+    for the 105-byte value the short form `0x69` matches byte-exactly);
+  * signature AlgorithmIdentifier is `rsaEncryption` (1.2.840.113549.1.1.1,
+    hash from digestAlgorithm = sha256) — classic PKCS#7 DigestInfo.
+* Attributes: contentType (1.9.3) = pkcs7-data, signingTime (1.9.5),
+  messageDigest (1.9.4).
+* Signer: device certificate (leaf carries certificatePolicies
+  **1.3.6.1.4.1.11256.2.3**), SID = issuerAndSerialNumber.
+
+### Trust store (`fw_libcrypto_get_trust_store`, backup type)
+
+Four CA certs hard-coded in libncrypto .rodata, extracted to
+`decbackup/certs/`:
+
+| .rodata off | size | subject |
+|---|---|---|
+| 0x8890 | 0x6b0 | Stormshield Network Security Enrollment Products CA |
+| 0x6b40 | 0x418 | NETASQ Firewall Certification Authority |
+| 0x8f40 | 0x601 | Stormshield Products Root CA |
+| 0x6f60 | 0x606 | Stormshield Product and Services Root CA |
+
+Verify parameters: `X509_V_FLAG_NO_CHECK_TIME` (expired device certs still
+verify — backups stay readable forever), explicit policy
+1.3.6.1.4.1.11256.2.3. The callback `fwcrypto_verify_any_nodate_callback`
+(0x11150) accepts errors {0, 9, 10} and 43 when
+`fw_libcrypto_is_netasq_issued` (issuer DER memcmp vs the NETASQ root).
+Net effect: signature-valid chain from leaf to an embedded root, dates
+ignored. Chain in vectors: device ← Stormshield Network Security Products
+CA (in the trailer) ← Stormshield Products Root CA (embedded).
+
+## 5. CLI grammar (`decbackup` main)
+
+getopt string `Pi:p:o:d`; usage (stderr, exit 1 when missing args/options):
+
+```
+Usage : () -i <backup> -o <output archive>
+                    [-p <password>] [-d : dump backup header]
+                    [-P : prompt for password]
+```
+
+(The empty parens are faithful: both `%s` args point at an empty string.)
+
+* `-p` more than once → `-p can only be specified once`, exit 1.
+* Password selection: `-p x` → x; `-P` → `t_getpass` prompt
+  `Enter backup password (<Enter> for none): ` which reads **/dev/tty**
+  (piped stdin is ignored: `-P` over a pipe with no tty → empty password →
+  13); no `-p`/`-P` on a tty → same prompt; otherwise empty password.
+* `-d` → on success prints `Header :\n<text up to NUL>\n`. Success is
+  otherwise silent (exit 0); failure prints
+  `decrypt and/or verify backup failed (%d)` (stderr) and exits 1.
+* Output file is created early (`fopen wb`) and **removed on every error
+  path**.
+* Clone extension: `--no-verify` (long option only — the original
+  getopt string `Pi:p:o:d` is unchanged and cannot collide with it).
+  It skips trailer parsing and all verification; the X field is still
+  read to locate the payload, so the structural floor (8) and padding
+  errors (13) remain.  A corrupted-but-in-range X can therefore yield
+  exit 0 with garbage content — that is the point of the switch.
+  A warning goes to stderr and exit 0 then means
+  "decrypted, not authenticated".
+
+## 6. Error codes (empirical matrix, real device vs clone — parity)
+
+`analysis/probes.py` renders this matrix as a static table, run locally
+against `tests/vectors/` (no device needed; the `real` column holds codes
+recorded on the device). The **maintained** parity check is
+`tests/test_decbackup.py` (run in CI); keep the two in sync.
+
+| code | meaning | proven by |
+|---|---|---|
+| 0 | success | all vectors |
+| 1 | input/output open failure | code path |
+| 6 | signature trailer unparsable / doesn't fit first chunk; crypto params missing | X=0 → 6; sed-shifted files → 6 |
+| 7 | verification failed (content digest, attribute signature, chain) | 1-byte ciphertext tamper → 7; cert bytes zeroed → 7; header edit → 7 |
+| 8 | file shorter than 0x400 | trunc.bkup → 8 |
+| 11 | short write to the output file (residual default err; seen when `-o /dev/stdout` truncates the stream) — **not reproduced in clone**: v4.2.8 short-write artifact with no clone code path | 4.2.8 binary, v1 probe to /dev/stdout |
+| 12 | unknown majversion (`Unknown backup majversion: %d`) or version gate (`Invalid archive`) | majversion=3 → 12; version=9 → 12 |
+| 13 | decrypt failed — in practice wrong password (EVP_CipherFinal padding) | wrongpass → 13 |
+| 32 | unsupported algo | algo=2 → 32 |
+
+**Verification is enforced**: an early "tampering is accepted" conclusion
+was an artifact of csh mangling `dd … 2>/dev/null` (all those tamper
+commands were silent no-ops). With surgical `dd conv=notrunc` patches the
+tool fails closed on every corrupted byte in the ciphertext, signature,
+attributes, or certificate regions.
+
+### Boundary probes (device, all derived from `test.bkup`)
+
+| probe | edit | code | conclusion |
+|---|---|---|---|
+| yt.bkup | +16 zero bytes appended | 13 | decryption is bounded by **filesize**, not the be32 Y field — Y is informational; trailing garbage lands in the last CBC block → padding fails |
+| ys.bkup | last 16 bytes removed | 13 | a file shorter than Y simply decrypts short (no separate Y error) |
+| mvx.bkup | `majversion=x` (same length) | 13 | non-numeric majversion → parse fails → **defaults to 1** (v1 path) like an absent key; "anything else → 12" applies to parsed numbers only |
+
+### CLI probes (device)
+
+| invocation | stderr |
+|---|---|
+| `decbackup -z` | `decbackup: illegal option -- z` + usage |
+| `-p a -p b …` | `-p can only be specified once` — **no usage dump** |
+| missing `-i`/`-o` | usage only |
+
+### The version gate (`fwcrypto_maj_get_version`, 0x11820)
+
+`cmp ax,1 → error 12 ("Invalid archive")` at 0x13194 on the flags&2 backup
+path. Observations (all same-length edits, X intact unless noted):
+
+| header `version` | real code | interpretation |
+|---|---|---|
+| `5.1.4` (real) | pass | parse fails → default 1 |
+| `1` | pass | parses to 1 |
+| `9` (−4 shift) | 12 | parses to 9 → gate **before** the X check |
+| `9    ` (padded) | 7 | trailing spaces → parse fails → default |
+| `10000`/`90000` | 7 | 5-digit values → parse fails → default |
+| `abcde`, `2.0.0` | 7 | parse fails → default |
+
+Empirical rule implemented: value **parses** only when it is leading
+whitespace + 1–4 digits + end (strict, no trailing chars); a parsed value
+≠ 1 → error 12. The digit-count cap (why 5-digit strings fail) is inferred,
+not read off `str_get_int_ex` conclusively — the 4-vs-3 boundary is
+untested. Real backups always carry dotted versions → always pass.
+
+## 7. Methodology gotchas (for future probes)
+
+1. **csh eats `2>/dev/null`** — `dd`/redirects with `2>` become silent
+   no-ops ("Unknown operand"). Tamper commands *must* omit it.
+2. **sed edits change file length** → everything after the header shifts →
+   the X field at 0x400 reads garbage → you measure the X check, not the
+   thing you probed. Only same-length substitutions, or patch with
+   `dd conv=notrunc`.
+3. `cmp` is not whitelisted; csh reports command-not-found as exit 1,
+   which looks exactly like "files differ". Use `openssl dgst -sha256`.
+4. Probe files: byte-identical local/VM copies verified by sha256
+   computed manually on both sides at extraction time (digests are not
+   stored in the repo), so device-observed codes apply to the vectors.
+
+## 8. Robustness contract (fuzzing)
+
+`analysis/fuzz.py` mutation-fuzzes container bytes and the PKCS#7/DER
+parsers against the contract: **any** input must end in a `BackupError`
+with a documented code, never a traceback, never a surviving output
+file, never a hang (5 s guard). Seeds are the real vectors plus every
+input that ever violated the contract (`$TMPDIR/opencode/fuzz_failures/`,
+in practice `/tmp/opencode/fuzz_failures/` — a machine-local, volatile
+scratch dir, not versioned; the pinned regression vectors are
+`extdup.bkup` + `lazyparse.bkup`); mutations cover bit flips, splices,
+truncations, X/Y field corruption and random files with plausible headers.
+
+The first campaign (60k iterations, 2 seeds) surfaced one systemic
+class: `cryptography` parses certificate fields **lazily**, so a
+structurally-valid-but-tampered cert loads fine and then explodes on
+`.subject` / `.public_key()` / `.extensions` — including
+`DuplicateExtension`, which derives from bare `Exception`. Both verify
+boundaries (`SignerInfo.verify`, `trust.verify_chain`) now convert any
+unexpected parser exception into the fail-closed error 7. Two crash
+inputs are pinned as vectors (`extdup.bkup`, `lazyparse.bkup`).
+Re-runs: 90k iterations / 3 seeds clean; re-run before every release.
+
+## 9. Clone deviations from the device (security hardening)
+
+Deliberate behavior changes where the clone is *not* device-faithful:
+
+* **Chain terminators**: a self-signed chain end must match an embedded
+  CA certificate **byte-exactly**. The device binds through an OpenSSL
+  store lookup to the genuine cert; the clone's earlier subject+serial
+  match was exploitable (forged chains accepted).
+* **Chain signature algs**: explicit allow-list — unknown OIDs rejected,
+  `…1.1.5` → SHA-1, MD5 not accepted.
+* **certificatePolicies**: an extension that fails to parse → reject
+  (previously fail-open).
+* **Issuers**: intermediate/root issuers must carry `CA:TRUE` (matches
+  the device's INVALID_CA).
+* **signerInfos**: **all** signerInfos are verified (previously only the
+  first).
+* **Structure**: duplicate or missing `contentType` authAttrs, unknown
+  PKCS#7 signature algs, and malformed DER children (child extending
+  beyond its parent, oversized OID components) → reject.
+* **pbkdf_iterations**: ≥ 2^31 → error 6; ASCII digits only. Device
+  analog: OpenSSL "iteration value is too great" (exact code unprobed).
+* **iv**: wrong-length iv / whitespace-laced hex → error 6 at parse time
+  (inferred).
+* **`-P`**: now actually prompts without echo on a tty (parity intent);
+  pipe-without-tty → empty password is unchanged (device-probed 13).
+* **Passwords**: non-UTF-8 passwords remain a clone limitation (the
+  device uses raw argv bytes).
+
+## 10. Open items / uncertainties
+
+* v1 KDF **empirically confirmed** on both VMs (§12). The IV window is
+  static-confirmed (identical `lea`-pool layout in both binaries) but
+  RC-invisible in probes (CBC padding ignores the IV and the digest can
+  never match a copied trailer); it is the pool[0:16] window.
+* Exact digit-count cap of the version gate parser (implemented ≤4).
+* Error code when the *output* file can't be created: assumed 1.
+* `pbkdf_iterations` default when the key is missing: assumed 1
+  (`mov esi, 1` near the getter); real files always carry the key.
+* A crafted `pbkdf_iterations` of ~10^9 stalls verification for minutes
+  on the clone AND on the device (the value is trusted straight from the
+  header) — DoS-by-input is a shared property, not a clone deviation.
+
+## 11. Test vectors (`tests/vectors/`)
+
+Made with `encbackup -i <tar> -o <bkup> -t all -p <pass>` on the device,
+fetched by base64-over-ssh, and cross-validated against the real
+`decbackup` output. Error vectors are byte-identical to the device-side
+probe files — verified by comparing digests manually on both sides at
+extraction time; the digests themselves were never recorded in the repo.
+
+Privacy note: the vectors are real device output and cannot be edited
+without breaking the signature they exercise, so they carry the lab
+device's certificate (public by design) and the default evaluation-VM
+serial; the payload tars are synthetic and the passwords are the test
+values shown below. No private key material is present in any vector.
+
+| vector | payload | password | code |
+|---|---|---|---|
+| test.bkup | test.tar (2 KiB) | `testpass` | 0 |
+| nopass.bkup | t2.tar | (empty) | 0 |
+| big.bkup | big.tar | `BigPass789` | 0 |
+| mid.bkup | mid.tar (23 KiB, multi-chunk) | `MidPass321` | 0 |
+| trunc/xzero/ct/cert/mv3/v9 | — | `testpass` | 8/6/7/7/12/7 |
+| v1probe.bkup / v1badkey.bkup | test.tar (§12, v1-encrypted) | `testpass` | 7 / 13 |
+
+## 12. Second VM: SNS v4.2.8
+
+Older box, same EVA1-VM hardware line, the same default evaluation-VM
+serial as the 5.1.4 box, clock
+pinned to 2020. All four binaries differ from 5.1.4
+(`decbackup fca8df91…`, `libncrypto.so ddca97b1…`). Its `decbackup` usage
+string lacks the `-P` line; `encbackup` still writes **majversion=2**
+(PBKDF2, 10000 iterations) with the identical container layout — so no
+release in this VM line emits v1.
+
+* **Cross-version compatibility (CONFIRMED)**: the clone decrypts a
+  v4.2.8-produced backup byte-exactly, and the v4.2.8 device `decbackup`
+  reproduces the same sha256. Same PKI chain as 5.1.4
+  (device ← Products CA ← Products Root CA).
+* **v1 path present and identical in structure**: `upd_update` (flags&2)
+  → `fwcrypto_get_backup_majversion` → `==1` branch calls
+  `fwcrypto_keyfrompasswd(pass, 0x10)` + `fwcrypto_ivfrompasswd(pass, 0x10)`
+  (0xd692/0xd6ac), then the same streaming decrypt + `VerifySignatureFinal`
+  tail — v1 archives are signed containers too, and VSI failure is still
+  fail-closed (error 6). The version gate (`cmp ax,1` → 12) is the same.
+* **v1 salt windows**: both binaries read the *same* windows of the shared
+  48-byte pool (key = pool+16, iv = pool+0). Resolved by `lea`
+  instruction-by-instruction in both (`sns` 0x16d8d→file 0x1b420,
+  0x16ac4→0x1b410; `sns428` 0x10d98→0x18030, 0x10aaf→0x18020), and
+  confirmed empirically with the probe matrix below.
+* **v1 KDF probe matrix** (v1 header via same-length `majversion=2→1`
+  edit of a real v4.2.8 backup, copied valid trailer, content re-encrypted
+  under each salt×iv combination; padding validity is the key oracle, CBC
+  IV cannot affect it):
+
+  | ciphertext made with | old-VM (4.2.8) | 5.1.4 VM |
+  |---|---|---|
+  | pool+16 key (correct) | 7 (both IVs) | 7 |
+  | shifted key `212807a5…` | 13 | 13 |
+
+  `7` = decryption succeeded, digest check failed (expected: the trailer's
+  messageDigest covers the original v2 content). This proves the key
+  window on both binaries; the IV window follows from the identical
+  `lea`-pool layout (RC-invisible by construction).
+* **4.2.8 embedded trust blobs** (libncrypto .data, six certs): the two
+  5.1.4 roots + Enrollment Products CA, **no NETASQ root**, plus three
+  service certs for the update path (`firmware.sns.local`,
+  `update.sns.local`, `signvmkit.sns.local`, issued by "Stormshield
+  Network Security CA"). The NETASQ-issuer special case in the verify
+  callback therefore postdates 4.2.8. 4.2.8 also exposes older API
+  surface (`fwcrypto_dec_maj_file`, `fwcrypto_check_maj`,
+  `fwcrypto_backup_read_algo`, 3DES/Blowfish/DES helpers).
+* **Error 11** appears on the old binary: the stream loop sets
+  `[err]=11` as the default before each output `fwrite` and a failing
+  `EVP_CipherFinal`/short-write path leaves it in place. Observed when
+  pointing `-o` at `/dev/stdout` (pipe semantics + `remove()` of the
+  symlink); a regular output file behaves as on 5.1.4.
+* **Ingestion channel** (SCP blocked, echo-chunks proved lossy — csh
+  `echo` corrupted some base64 payloads at identical length): pipe bytes
+  straight through ssh stdin into `dd of=/tmp/x bs=<len> count=1`, then
+  `openssl base64 -A -d -in /tmp/x -out /tmp/y`. The `-A` flag is
+  required on this box's OpenSSL 1.1.1k for single-line payloads;
+  verify with `md5` on both ends.

{decbackup-0.1.0 → decbackup-0.2.0}/decbackup/__init__.py

@@ -5,6 +5,6 @@ container handling of ``libncrypto.so`` from Stormshield SNS v5.1.4,
 derived by reverse engineering (see ``RECON.md``).
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 from .backup import BackupError, decrypt_backup  # noqa: F401