|
| 1 | +# kduma/pcf-sig |
| 2 | + |
| 3 | +PHP implementation of **PCF-SIG v1.0**, the PCF Cryptographic Signatures |
| 4 | +profile. Mirrors the [normative specification][spec] and the [Rust reference |
| 5 | +implementation][rust] field-for-field. |
| 6 | + |
| 7 | +[spec]: ../../../specs/PCF-SIG-spec-v1.0.txt |
| 8 | +[rust]: ../../../reference/PCF-SIG-v1.0/ |
| 9 | + |
| 10 | +## Install |
| 11 | + |
| 12 | +```sh |
| 13 | +composer require kduma/pcf kduma/pcf-sig |
| 14 | +``` |
| 15 | + |
| 16 | +## What it adds |
| 17 | + |
| 18 | +Two new PCF partition types layered on top of the [`kduma/pcf`](../pcf/) |
| 19 | +container, without changing the PCF byte format: |
| 20 | + |
| 21 | +| Type | Name | Holds | |
| 22 | +|--------------|--------------|------------------------------------------------------| |
| 23 | +| `0xAAAB0001` | `PCFSIG_KEY` | One signer's public key, identified by SHA-256 fingerprint of the key bytes | |
| 24 | +| `0xAAAB0002` | `PCFSIG_SIG` | One Manifest enumerating signed partitions + the signature over the Manifest | |
| 25 | + |
| 26 | +A **Manifest** binds the *protected fields* of each covered partition: |
| 27 | +`uid`, `partitionType`, `label`, `usedBytes`, `dataHashAlgo`, `dataHash`. It |
| 28 | +does NOT bind `startOffset` or `maxLength`, so PCF compaction and other |
| 29 | +relocations preserve signature validity as long as partition bytes do not |
| 30 | +change. |
| 31 | + |
| 32 | +## Algorithm support |
| 33 | + |
| 34 | +| `sig_algo_id` | Algorithm | This release | |
| 35 | +|---------------|---------------------|--------------| |
| 36 | +| 1 | Ed25519 (RFC 8032) | implemented (MUST) | |
| 37 | +| 2, 4, 5, 7 | RSA-PSS / PKCS1v15 | registry only | |
| 38 | +| 16, 18 | ECDSA P-256 / P-521 | registry only | |
| 39 | +| 32 | X.509 chain | registry only | |
| 40 | + |
| 41 | +Algorithms marked *registry only* are recognised at parse time and reported as |
| 42 | +`ManifestVerdict::Unverifiable` (with `UnverifiableReason::UnsupportedSigAlgo`) |
| 43 | +rather than `Malformed`. Adding a full implementation for any of them is a |
| 44 | +pure addition that does not touch the on-disk format. |
| 45 | + |
| 46 | +Hash algorithm constraint: signed partitions MUST use a cryptographic |
| 47 | +`dataHashAlgo` (SHA-256, SHA-512, BLAKE3). The Writer refuses to sign |
| 48 | +weakly-hashed partitions; the Verifier rejects them per entry. |
| 49 | + |
| 50 | +## Usage |
| 51 | + |
| 52 | +```php |
| 53 | +use Kduma\PCF\Container; |
| 54 | +use Kduma\PCF\HashAlgo; |
| 55 | +use Kduma\PCFSIG\ManifestVerdict; |
| 56 | +use Kduma\PCFSIG\SignPartitions; |
| 57 | +use Kduma\PCFSIG\SigningMaterial; |
| 58 | +use Kduma\PCFSIG\Verify; |
| 59 | + |
| 60 | +$c = Container::create(); |
| 61 | +$alpha = str_repeat("\x11", 16); |
| 62 | +$c->addPartition(0x10, $alpha, 'alpha', 'Hello, PCF-SIG!', 0, HashAlgo::Sha256); |
| 63 | + |
| 64 | +$signer = SigningMaterial::ed25519FromSeed(str_repeat("\x42", 32)); |
| 65 | +SignPartitions::run( |
| 66 | + $c, $signer, [$alpha], |
| 67 | + str_repeat("\x33", 16), |
| 68 | + str_repeat("\x22", 16), |
| 69 | + 0, 'pcfsig', 'pcfkey', |
| 70 | +); |
| 71 | + |
| 72 | +foreach (Verify::allWithRecheck($c) as $report) { |
| 73 | + if ($report->verdict === ManifestVerdict::Valid) { |
| 74 | + printf("signature valid; %d entries covered\n", count($report->entries)); |
| 75 | + } |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +## Cross-port test vector parity |
| 80 | + |
| 81 | +The shipped `testdata/canonical.bin` is byte-identical to the canonical vector |
| 82 | +produced by the Rust reference and the TypeScript port. SHA-256: |
| 83 | +`b158e2f5b160d72cea3226af2041f8d18aa75b3db6cb85faeca5df7879871307`. |
| 84 | + |
| 85 | +```sh |
| 86 | +composer gen-testvector -- /tmp/php.bin |
| 87 | +``` |
| 88 | + |
| 89 | +The test suite asserts byte-exact equality on every CI run. |
| 90 | + |
| 91 | +## Dependencies |
| 92 | + |
| 93 | +- `kduma/pcf` — the PCF base container library (same version as pcf-sig). |
| 94 | +- `ext-sodium` — PHP's bundled libsodium, used for Ed25519 sign/verify |
| 95 | + (`sodium_crypto_sign_detached` / `sodium_crypto_sign_verify_detached`). |
| 96 | + Available in PHP 7.2+ without external dependencies. |
| 97 | +- `ext-hash` — PHP's bundled hash extension, used for SHA-256 fingerprints. |
| 98 | + |
| 99 | +No Composer crypto dependencies; all signing/hashing runs through built-in |
| 100 | +PHP extensions. |
0 commit comments