Debian Codegraph @

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

raw
1 # Zero-Length Attribute Fixture Implementation Plan
2
3 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
5 **Goal:** Add a pre-generated PKCS12 fixture carrying zero-length OCTET STRING and BIT STRING bag attributes, and a regression test that loads it and verifies the attributes are returned as empty strings.
6
7 **Architecture:** A developer-only Perl generation script builds a minimal PKCS12 from scratch using `Convert::ASN1` (unencrypted SafeContents, dummy MacData). The fixture is committed to `certs/`. The test loads it via `info_as_hash()`, which does not verify the MAC, so the dummy MacData is harmless.
8
9 **Tech Stack:** Perl 5, `Convert::ASN1`, `MIME::Base64` (core), `Crypt::OpenSSL::PKCS12`, `Test::More`
10
11 ## Global Constraints
12
13 - Work on branch `fix/get-hex-null-termination` throughout
14 - Do not run the generation script during `make test` — it is a one-off developer tool
15 - Password for the fixture is `test`
16 - Custom attribute OIDs: `1.2.3.100` (OCTET STRING), `1.2.3.101` (BIT STRING)
17 - `Convert::ASN1` is a develop-only dependency — do not add it to the runtime `requires` block
18 - All test assertions use `Test::More`
19 - Run `prove -lv t/pkcs12-info-zero-length-attributes.t` after each test change
20
21 ---
22
23 ### Task 1: Add Convert::ASN1 to cpanfile and switch to the fix branch
24
25 **Files:**
26 - Modify: `cpanfile`
27
28 **Interfaces:**
29 - Produces: `Convert::ASN1` available for the generation script
30
31 - [ ] **Step 1: Switch to the fix branch**
32
33 ```bash
34 git checkout fix/get-hex-null-termination
35 ```
36
37 Expected: `Switched to branch 'fix/get-hex-null-termination'`
38
39 - [ ] **Step 2: Add the develop dependency**
40
41 Open `cpanfile`. At the end of the file add:
42
43 ```perl
44 on 'develop' => sub {
45 requires 'Convert::ASN1';
46 };
47 ```
48
49 - [ ] **Step 3: Install it**
50
51 ```bash
52 carton install
53 ```
54
55 Expected: `Complete!` (or `Convert::ASN1 is up to date`)
56
57 - [ ] **Step 4: Commit**
58
59 ```bash
60 git add cpanfile cpanfile.snapshot
61 git commit -m "build: add Convert::ASN1 as develop dependency for fixture generation"
62 ```
63
64 ---
65
66 ### Task 2: Write the fixture generation script
67
68 **Files:**
69 - Create: `scripts/generate-zero-length-attr-fixture.pl`
70
71 **Interfaces:**
72 - Consumes: `certs/test-cert.pem` (existing)
73 - Produces: `certs/zero-length-attrs.p12`
74
75 Key facts about the PKCS12 DER structure this script builds:
76
77 - The MAC section (`macData`) must be present and structurally valid even if the MAC bytes are wrong, because OpenSSL ≤ 1.1.0 accesses `pkcs12->mac` directly without a NULL check in the `info_as_hash()` path.
78 - `info_as_hash()` does **not** call `PKCS12_verify_mac()`, so the MAC value does not need to be correct.
79 - The SafeContents is placed in an unencrypted PKCS7 Data ContentInfo so no decryption is needed.
80 - Zero-length OCTET STRING DER bytes: `\x04\x00`
81 - Zero-length BIT STRING DER bytes: `\x03\x01\x00` (length=1, zero unused bits, no data → `ASN1_STRING_length()` returns 0)
82
83 - [ ] **Step 1: Create the script**
84
85 ```perl
86 #!/usr/bin/perl
87 use strict;
88 use warnings;
89 use MIME::Base64 qw(decode_base64);
90 use Convert::ASN1;
91
92 # ── OIDs ────────────────────────────────────────────────────────────────────
93 my $OID_PKCS7_DATA = '1.2.840.113549.1.7.1';
94 my $OID_CERT_BAG = '1.2.840.113549.1.12.10.1.3';
95 my $OID_X509_CERT = '1.2.840.113549.1.9.22.1';
96 my $OID_SHA1 = '1.3.14.3.2.26';
97 my $OID_HMAC_SHA1 = '1.2.840.113549.2.7';
98 my $OID_ZERO_OCTET = '1.2.3.100';
99 my $OID_ZERO_BIT = '1.2.3.101';
100
101 # ── Load certificate DER from PEM ───────────────────────────────────────────
102 my $cert_file = 'certs/test-cert.pem';
103 open my $fh, '<', $cert_file or die "Cannot open $cert_file: $!";
104 my $cert_pem = do { local $/; <$fh> };
105 close $fh;
106 (my $cert_b64 = $cert_pem) =~ s/-----[^-]+-----//g;
107 $cert_b64 =~ s/\s+//g;
108 my $cert_der = decode_base64($cert_b64);
109
110 # ── ASN.1 schema ─────────────────────────────────────────────────────────────
111 my $asn = Convert::ASN1->new;
112 $asn->prepare(q{
113 PFX ::= SEQUENCE {
114 version INTEGER,
115 authSafe ContentInfo,
116 macData MacData OPTIONAL
117 }
118 ContentInfo ::= SEQUENCE {
119 contentType OBJECT IDENTIFIER,
120 content [0] EXPLICIT ANY OPTIONAL
121 }
122 MacData ::= SEQUENCE {
123 mac DigestInfo,
124 macSalt OCTET STRING,
125 iterations INTEGER OPTIONAL
126 }
127 DigestInfo ::= SEQUENCE {
128 digestAlgorithm AlgorithmIdentifier,
129 digest OCTET STRING
130 }
131 AlgorithmIdentifier ::= SEQUENCE {
132 algorithm OBJECT IDENTIFIER,
133 parameters ANY OPTIONAL
134 }
135 SafeContents ::= SEQUENCE OF SafeBag
136 SafeBag ::= SEQUENCE {
137 bagId OBJECT IDENTIFIER,
138 bagValue [0] EXPLICIT ANY,
139 bagAttributes SET OF Attribute OPTIONAL
140 }
141 Attribute ::= SEQUENCE {
142 attrType OBJECT IDENTIFIER,
143 attrValues SET OF ANY
144 }
145 CertBag ::= SEQUENCE {
146 certId OBJECT IDENTIFIER,
147 certValue [0] EXPLICIT ANY
148 }
149 }) or die $asn->error;
150
151 # ── Encode helpers ───────────────────────────────────────────────────────────
152 my $attr_asn = $asn->find('Attribute') or die $asn->error;
153 my $certbag_asn = $asn->find('CertBag') or die $asn->error;
154 my $safebag_asn = $asn->find('SafeBag') or die $asn->error;
155 my $sc_asn = $asn->find('SafeContents') or die $asn->error;
156 my $ci_asn = $asn->find('ContentInfo') or die $asn->error;
157 my $mac_asn = $asn->find('MacData') or die $asn->error;
158 my $pfx_asn = $asn->find('PFX') or die $asn->error;
159
160 # ── Build certificate bag value (CertBag) ───────────────────────────────────
161 my $certbag_der = $certbag_asn->encode({
162 certId => $OID_X509_CERT,
163 certValue => $cert_der,
164 }) or die $certbag_asn->error;
165
166 # ── Build the two zero-length attributes ─────────────────────────────────────
167 # attrValues contains raw DER — Convert::ASN1 passes ANY through as-is
168 my $attr_zero_octet = $attr_asn->encode({
169 attrType => $OID_ZERO_OCTET,
170 attrValues => [ "\x04\x00" ], # zero-length OCTET STRING
171 }) or die $attr_asn->error;
172
173 my $attr_zero_bit = $attr_asn->encode({
174 attrType => $OID_ZERO_BIT,
175 attrValues => [ "\x03\x01\x00" ], # zero-length BIT STRING
176 }) or die $attr_asn->error;
177
178 # ── Build the certificate SafeBag ────────────────────────────────────────────
179 my $safebag_der = $safebag_asn->encode({
180 bagId => $OID_CERT_BAG,
181 bagValue => $certbag_der,
182 bagAttributes => [
183 { attrType => $OID_ZERO_OCTET, attrValues => [ "\x04\x00" ] },
184 { attrType => $OID_ZERO_BIT, attrValues => [ "\x03\x01\x00" ] },
185 ],
186 }) or die $safebag_asn->error;
187
188 # ── Build SafeContents ────────────────────────────────────────────────────────
189 my $sc_der = $sc_asn->encode([ {
190 bagId => $OID_CERT_BAG,
191 bagValue => $certbag_der,
192 bagAttributes => [
193 { attrType => $OID_ZERO_OCTET, attrValues => [ "\x04\x00" ] },
194 { attrType => $OID_ZERO_BIT, attrValues => [ "\x03\x01\x00" ] },
195 ],
196 } ]) or die $sc_asn->error;
197
198 # ── Wrap SafeContents in OCTET STRING, then in ContentInfo ───────────────────
199 # PKCS7 Data: content = [0] EXPLICIT OCTET STRING { SafeContents DER }
200 my $octet_sc;
201 {
202 use Convert::ASN1;
203 my $a = Convert::ASN1->new;
204 $a->prepare('wrap OCTET STRING');
205 $octet_sc = $a->find('wrap')->encode($sc_der) or die $a->error;
206 }
207
208 my $auth_safe_der = $ci_asn->encode({
209 contentType => $OID_PKCS7_DATA,
210 content => $octet_sc,
211 }) or die $ci_asn->error;
212
213 # ── Build dummy MacData (structurally valid, MAC bytes are wrong) ─────────────
214 # MacData must be present so pkcs12->mac is not NULL on OpenSSL <= 1.1.0.
215 # info_as_hash() does not call PKCS12_verify_mac() so correctness is not needed.
216 my $mac_der = $mac_asn->encode({
217 mac => {
218 digestAlgorithm => { algorithm => $OID_HMAC_SHA1 },
219 digest => "\x00" x 20, # 20 dummy bytes
220 },
221 macSalt => "\x00" x 8,
222 iterations => 2048,
223 }) or die $mac_asn->error;
224
225 # ── Assemble PFX ─────────────────────────────────────────────────────────────
226 my $pfx_der = $pfx_asn->encode({
227 version => 3,
228 authSafe => {
229 contentType => $OID_PKCS7_DATA,
230 content => $octet_sc,
231 },
232 macData => {
233 mac => {
234 digestAlgorithm => { algorithm => $OID_HMAC_SHA1 },
235 digest => "\x00" x 20,
236 },
237 macSalt => "\x00" x 8,
238 iterations => 2048,
239 },
240 }) or die $pfx_asn->error;
241
242 # ── Write output ─────────────────────────────────────────────────────────────
243 my $out_file = 'certs/zero-length-attrs.p12';
244 open my $out, '>', $out_file or die "Cannot write $out_file: $!";
245 binmode $out;
246 print $out $pfx_der;
247 close $out;
248
249 print "Written: $out_file\n";
250 ```
251
252 - [ ] **Step 2: Make executable**
253
254 ```bash
255 chmod +x scripts/generate-zero-length-attr-fixture.pl
256 ```
257
258 - [ ] **Step 3: Run the script**
259
260 ```bash
261 perl -Ilocal/lib/perl5 scripts/generate-zero-length-attr-fixture.pl
262 ```
263
264 Expected output:
265 ```
266 Written: certs/zero-length-attrs.p12
267 ```
268
269 - [ ] **Step 4: Verify the fixture is parseable by OpenSSL**
270
271 ```bash
272 openssl pkcs12 -info -in certs/zero-length-attrs.p12 -passin pass:test -noout 2>&1 | head -10
273 ```
274
275 Expected: output containing `PKCS7 Data` and `Certificate bag` with no fatal error (MAC verify error is acceptable here since we used a dummy MAC).
276
277 - [ ] **Step 5: Verify the fixture loads via Crypt::OpenSSL::PKCS12**
278
279 ```bash
280 perl -Iblib/lib -Iblib/arch -e '
281 use Crypt::OpenSSL::PKCS12;
282 my $p12 = Crypt::OpenSSL::PKCS12->new_from_file("certs/zero-length-attrs.p12");
283 print "loaded ok\n" if $p12;
284 my $h = eval { $p12->info_as_hash("test") };
285 print "info_as_hash ok\n" unless $@;
286 print "error: $@\n" if $@;
287 '
288 ```
289
290 Expected:
291 ```
292 loaded ok
293 info_as_hash ok
294 ```
295
296 If `info_as_hash` fails with a MAC or structure error, investigate the MacData encoding — check that `pkcs12->mac` is not NULL by trying on OpenSSL ≤ 1.1.0 if available. The dummy MAC bytes are intentionally wrong; only the structure must be valid.
297
298 - [ ] **Step 6: Commit**
299
300 ```bash
301 git add scripts/generate-zero-length-attr-fixture.pl
302 git commit -m "scripts: add fixture generator for zero-length OCTET/BIT STRING bag attributes"
303 ```
304
305 ---
306
307 ### Task 3: Write the regression test
308
309 **Files:**
310 - Create: `t/pkcs12-info-zero-length-attributes.t`
311
312 **Interfaces:**
313 - Consumes: `certs/zero-length-attrs.p12` (from Task 2)
314 - Produces: regression guard for `get_hex()` zero-length NUL-termination fix
315
316 The test navigates `info_as_hash()` output to find attributes keyed by OID string. The hash structure is:
317 ```
318 {
319 pkcs7_data => [
320 {
321 bags => [
322 {
323 type => 'certificate_bag',
324 bag_attributes => {
325 '1.2.3.100' => '', # zero-length OCTET STRING → get_hex returns ""
326 '1.2.3.101' => '', # zero-length BIT STRING → get_hex returns ""
327 }
328 }
329 ]
330 }
331 ]
332 }
333 ```
334
335 - [ ] **Step 1: Write the failing test (pre-fixture)**
336
337 ```perl
338 #!/usr/bin/perl
339
340 # Regression test for the zero-length OCTET STRING / BIT STRING path of
341 # print_attribute() / get_hex(). Before the fix, get_hex() never wrote a NUL
342 # terminator, leaving *attribute uninitialised when length == 0. Downstream
343 # strlen() on an unterminated buffer is undefined behaviour.
344 #
345 # The fixture certs/zero-length-attrs.p12 carries two custom bag attributes:
346 # 1.2.3.100 → zero-length OCTET STRING (ASN1_STRING_length() == 0)
347 # 1.2.3.101 → zero-length BIT STRING (ASN1_STRING_length() == 0)
348 #
349 # info_as_hash() does not call PKCS12_verify_mac(), so the fixture's dummy MAC
350 # is never checked.
351
352 use strict;
353 use warnings;
354 use Test::More;
355 use File::Spec::Functions qw(catfile);
356
357 BEGIN { use_ok('Crypt::OpenSSL::PKCS12') }
358
359 my $fixture = catfile('certs', 'zero-length-attrs.p12');
360
361 SKIP: {
362 skip "fixture $fixture not found", 5 unless -f $fixture;
363
364 my $p12 = Crypt::OpenSSL::PKCS12->new_from_file($fixture);
365 ok($p12, 'loaded zero-length-attrs.p12');
366
367 my $hash = eval { $p12->info_as_hash('test') };
368 is($@, '', 'info_as_hash() did not croak');
369 ok(ref $hash eq 'HASH', 'info_as_hash() returned a hashref');
370
371 # Locate bag_attributes in pkcs7_data bags
372 my $attrs;
373 OUTER: for my $section (@{ $hash->{pkcs7_data} // [] }) {
374 for my $bag (@{ $section->{bags} // [] }) {
375 if (exists $bag->{bag_attributes}{'1.2.3.100'}) {
376 $attrs = $bag->{bag_attributes};
377 last OUTER;
378 }
379 }
380 }
381
382 SKIP: {
383 skip 'bag_attributes not found in pkcs7_data', 2 unless defined $attrs;
384
385 is($attrs->{'1.2.3.100'}, '',
386 'zero-length OCTET STRING attribute is empty string — get_hex() NUL-terminates');
387
388 is($attrs->{'1.2.3.101'}, '',
389 'zero-length BIT STRING attribute is empty string — get_hex() NUL-terminates');
390 }
391 }
392
393 done_testing;
394 ```
395
396 Save to `t/pkcs12-info-zero-length-attributes.t`.
397
398 - [ ] **Step 2: Run the test — confirm it passes (fixture exists from Task 2)**
399
400 ```bash
401 prove -lv t/pkcs12-info-zero-length-attributes.t
402 ```
403
404 Expected:
405 ```
406 ok 1 - use Crypt::OpenSSL::PKCS12
407 ok 2 - loaded zero-length-attrs.p12
408 ok 3 - info_as_hash() did not croak
409 ok 4 - info_as_hash() returned a hashref
410 ok 5 - zero-length OCTET STRING attribute is empty string — get_hex() NUL-terminates
411 ok 6 - zero-length BIT STRING attribute is empty string — get_hex() NUL-terminates
412 1..6
413 ```
414
415 If the attributes are not found in `pkcs7_data` but the test passes the first 4 assertions, check whether the bags are under `pkcs7_encrypted_data` instead. Update the navigation loop to check both sections.
416
417 - [ ] **Step 3: Run the full test suite to confirm no regressions**
418
419 ```bash
420 prove -lr -l -b -I inc t
421 ```
422
423 Expected: all tests pass.
424
425 - [ ] **Step 4: Commit**
426
427 ```bash
428 git add t/pkcs12-info-zero-length-attributes.t
429 git commit -m "test: add regression test for zero-length OCTET/BIT STRING bag attributes"
430 ```
431
432 ---
433
434 ### Task 4: Commit the fixture and write scripts/README.md
435
436 **Files:**
437 - Modify: `certs/zero-length-attrs.p12` (commit the generated binary)
438 - Create: `scripts/README.md`
439
440 **Interfaces:**
441 - Produces: committed fixture and documentation
442
443 - [ ] **Step 1: Commit the fixture**
444
445 ```bash
446 git add certs/zero-length-attrs.p12
447 git commit -m "certs: add zero-length-attrs.p12 fixture for get_hex() regression test"
448 ```
449
450 - [ ] **Step 2: Write scripts/README.md**
451
452 ```markdown
453 # scripts/
454
455 Helper scripts for maintainers. These are developer tools and are **not**
456 run as part of the test suite (`make test`).
457
458 ## test.sh
459
460 Runs the full build and test cycle against each installed OpenSSL version
461 (3.x, 3.0, 3.5, 4.x). Requires Carton and the relevant OpenSSL versions
462 installed under `/opt/homebrew/opt/`.
463
464 Usage:
465
466 bash scripts/test.sh
467
468 ## generate-zero-length-attr-fixture.pl
469
470 Generates `certs/zero-length-attrs.p12`, a minimal PKCS12 fixture that
471 carries two custom bag attributes with zero-length ASN.1 values:
472
473 | OID | Type | Purpose |
474 |-----------|--------------|--------------------------------------|
475 | 1.2.3.100 | OCTET STRING | Exercises `V_ASN1_OCTET_STRING` path |
476 | 1.2.3.101 | BIT STRING | Exercises `V_ASN1_BIT_STRING` path |
477
478 These are used by `t/pkcs12-info-zero-length-attributes.t` to guard against
479 regression of the `get_hex()` NUL-termination bug (issue #63, PR #65).
480
481 **Why a generation script?** The standard `openssl pkcs12` CLI cannot attach
482 custom bag attributes, and `Crypt::OpenSSL::PKCS12->create()` does not
483 expose bag attribute APIs. The script builds a minimal PKCS12 DER structure
484 from scratch using `Convert::ASN1`.
485
486 **When to re-run:** Only if `certs/test-cert.pem` changes. The generated
487 fixture is pre-committed to `certs/` and does not need to be regenerated
488 on every build.
489
490 **Requires:** `Convert::ASN1` (install with `carton install`).
491
492 Usage:
493
494 perl -Ilocal/lib/perl5 scripts/generate-zero-length-attr-fixture.pl
495 ```
496
497 - [ ] **Step 3: Commit README**
498
499 ```bash
500 git add scripts/README.md
501 git commit -m "docs: add scripts/README.md documenting helper scripts"
502 ```
503
504 - [ ] **Step 4: Push the branch**
505
506 ```bash
507 git push origin fix/get-hex-null-termination
508 ```
509
510 ---
511
512 ## Self-Review
513
514 **Spec coverage:**
515 - Generation script (`scripts/generate-zero-length-attr-fixture.pl`) ✓ Task 2
516 - Fixture (`certs/zero-length-attrs.p12`) ✓ Tasks 2 & 4
517 - Test (`t/pkcs12-info-zero-length-attributes.t`) ✓ Task 3
518 - `scripts/README.md` ✓ Task 4
519 - `cpanfile` develop dependency ✓ Task 1
520
521 **Placeholder check:** No TBDs. All code blocks are complete. The "If the attributes are not found" note in Task 3 Step 2 gives a concrete remediation path, not a vague instruction.
522
523 **Type consistency:** OID strings `1.2.3.100` / `1.2.3.101` used consistently in both generation script and test. Password `test` consistent throughout. Branch `fix/get-hex-null-termination` named in Task 1 Step 1.