Debian Codegraph @

docs/superpowers/specs/2026-06-19-zero-length-attr-fixture-design.md

raw
1 # Zero-Length OCTET STRING / BIT STRING Attribute Fixture
2
3 **Date:** 2026-06-19
4 **Branch:** fix/get-hex-null-termination
5 **Related:** PR #65, Issue #63
6
7 ## Context
8
9 `get_hex()` in `PKCS12.xs` previously left `*attribute` without a NUL terminator when called with a zero-length input. The fix (PR #65) adds `*out = '\0'` after the loop and bumps both `Renew` call sites from `length * 4` to `length * 4 + 1`. Copilot review requested a regression test covering the zero-length path. No existing fixture carries a zero-length OCTET STRING or BIT STRING bag attribute, and the standard `openssl pkcs12` CLI cannot produce one. A pre-generated fixture and dedicated test are needed.
10
11 ## Generation Script
12
13 **File:** `scripts/generate-zero-length-attr-fixture.pl`
14
15 **Steps:**
16 1. Load `certs/test-cert.pem` and `certs/test-key.pem` (existing fixtures, no new cert generation)
17 2. Call `Crypt::OpenSSL::PKCS12->create()` to produce a baseline PKCS12 in memory
18 3. Decode the raw DER with `Convert::ASN1` using the PKCS12 / SafeContents schema
19 4. Locate the first certificate bag's `bagAttributes` sequence
20 5. Append two new attributes:
21 - OID `1.2.3.100` → zero-length OCTET STRING (`04 00`)
22 - OID `1.2.3.101` → zero-length BIT STRING (`03 01 00`)
23 6. Re-encode and write to `certs/zero-length-attrs.p12`
24
25 The script is a one-off developer tool — it is not run during `make test`. Re-run only if `test-cert.pem` or `test-key.pem` change.
26
27 **Dependency:** `Convert::ASN1` (added to `cpanfile` as a develop dependency).
28
29 ## Fixture
30
31 **File:** `certs/zero-length-attrs.p12`
32
33 Pre-generated by the script above and committed to the repository. Contains one certificate bag with two custom bag attributes: a zero-length OCTET STRING at OID `1.2.3.100` and a zero-length BIT STRING at OID `1.2.3.101`. Password: `test`.
34
35 ## Test File
36
37 **File:** `t/pkcs12-info-zero-length-attributes.t`
38
39 1. Load `certs/zero-length-attrs.p12` with password `test`
40 2. Call `info()` — assert no croak, returns non-empty string
41 3. Call `info_as_hash()` — assert no croak, returns a hashref
42 4. Locate bag attribute for OID `1.2.3.100` (OCTET STRING) — assert it is defined and exactly `""` (empty string, not garbage)
43 5. Locate bag attribute for OID `1.2.3.101` (BIT STRING) — same assertion
44
45 No heap-poisoning loop required (unlike the UTF8STRING test) — the bug causes hard UB on zero-length, so a single call is sufficient. No OpenSSL version skips needed — the fixture uses standard PKCS12 with no secret bags or RC2.
46
47 ## Documentation
48
49 **File:** `scripts/README.md`
50
51 Documents each script in `scripts/`. Entry for `generate-zero-length-attr-fixture.pl` explains:
52 - Why the standard `openssl pkcs12` CLI cannot produce zero-length bag attributes
53 - Which OIDs and attribute types are embedded
54 - That `certs/zero-length-attrs.p12` is pre-committed and only needs regenerating if the base cert/key fixtures change
55
56 ## Dependencies
57
58 Add to `cpanfile`:
59
60 ```
61 on 'develop' => sub {
62 requires 'Convert::ASN1';
63 };
64 ```
65
66 `Convert::ASN1` is only needed to run the generation script, not for the module itself or its test suite.
67
68 ## Verification
69
70 1. Run `perl scripts/generate-zero-length-attr-fixture.pl` — confirms `certs/zero-length-attrs.p12` is written without error
71 2. Run `prove -lv t/pkcs12-info-zero-length-attributes.t` — all assertions pass
72 3. Run full suite `prove -lr -l -b -I inc t` — all 357+ tests still pass
73 4. Confirm `openssl pkcs12 -info -in certs/zero-length-attrs.p12 -passin pass:test -noout` does not error