PCF-SIG: trust patterns A (key attestations) and B (key endorsement)

Two ways for an application to express trust without X.509 are now
fully described in spec Section 12 and supported by the reference
implementation:

Pattern A (Section 12.1): self-binding key attestations. Application-
private TLV entries in PCFSIG_KEY (tag range 0x8000-0xFFFF) MAY carry
a JWT, SCITT statement, or custom signed envelope. The attestation MUST
internally commit to the key's SHA-256 fingerprint, since the fingerprint
field itself covers only key_data and not the TLV stream.

Pattern B (Section 12.2): key endorsement via countersignature. A "CA"
emits a PCFSIG_SIG whose manifest covers the leaf signer's PCFSIG_KEY
partition by uid. This binds the CA cryptographically to the leaf's key
material via the partition's data_hash. A new verify::key_endorsements()
helper returns the set of signers that endorse a given key fingerprint;
the application composes that with its trusted-CA set into a trust
decision.

Section 12.2.1 describes three Pattern B issuance workflows (file
round-trip, stateless server, offline pre-issued). The recommended
stateless workflow is supported by new endorse::issue_endorsement and
endorse::embed_endorsement helpers: the CA never sees the leaf's
container file and needs no per-issuance state. The same response is
valid in any PCF file in which the leaf KEY partition is reproduced
byte-identically (license pattern).

Includes 7 new integration tests covering single-hop endorsement, the
stateless workflow, durability across files, weak-hash rejection, and
the orthogonality of key endorsement vs leaf data integrity.

https://claude.ai/code/session_01ST4PcjqvobURus32WuyEi5

Author: claude

reference/PCF-SIG-v1.0/README.md

@@ -75,6 +75,62 @@ for report in verify_all_with_recheck(&mut c)? {
 # Ok::<(), pcf_sig::Error>(())
 ```
 
+## Trust patterns
+
+The profile defines two non-X.509 ways for an application to express trust;
+both are described in spec Section 12.
+
+**Pattern A — self-binding key attestations.** Carry a JWT, SCITT statement,
+or custom signed envelope as an application-private TLV entry (tag range
+`0x8000..0xFFFF`) inside the `PCFSIG_KEY` partition (Section 6.4). The
+attestation MUST internally commit to the key's SHA-256 fingerprint (e.g.
+JWT `cnf.jkt`); otherwise the binding is meaningless because the fingerprint
+covers only `key_data`, not the TLV. The application verifies the
+attestation independently of PCF-SIG.
+
+**Pattern B — key endorsement via countersignature.** A "CA" emits a
+`PCFSIG_SIG` partition whose manifest covers the leaf signer's `PCFSIG_KEY`
+partition by uid. Verifiers report it like any other signature; the
+application checks whether any trusted CA fingerprint endorses the leaf key.
+
+```rust
+use pcf_sig::{key_endorsements, verify_all_with_recheck};
+
+let reports = verify_all_with_recheck(&mut container)?;
+let endorsers = key_endorsements(&mut container, &reports, &leaf_fingerprint)?;
+let trusted = endorsers.iter().any(|fp| my_trusted_ca_set.contains(fp));
+# Ok::<(), pcf_sig::Error>(())
+```
+
+For Pattern B the CA does NOT need the leaf's PCF file. The stateless
+workflow (spec 12.2.1 W2): the client sends only the leaf key bytes plus the
+planned partition identity; the CA returns a self-contained response that
+the client embeds locally.
+
+```rust
+use pcf_sig::{embed_endorsement, issue_endorsement, EndorsementRequest, KeyFormat};
+use pcf::HashAlgo;
+
+// CA side (stateless; no I/O, no file):
+let request = EndorsementRequest {
+    key_format: KeyFormat::Ed25519Raw,
+    key_data: leaf_public_key_bytes,
+    intended_uid: agreed_uid,           // stable across leaf and CA
+    intended_label: agreed_label,
+    data_hash_algo: HashAlgo::Sha256,
+};
+let response = issue_endorsement(&ca_signer, &request, signed_at)?;
+
+// Client side: embed into the local container:
+embed_endorsement(&mut container, &response, ca_key_uid, ca_sig_uid, "ca-key", "ca-sig")?;
+# Ok::<(), pcf_sig::Error>(())
+```
+
+Because the response commits to the leaf `PCFSIG_KEY` bytes (not to any file
+location), a client may also cache and re-use the same response across many
+PCF files in which the leaf KEY partition is reproduced byte-identical
+(workflow W3, license pattern).
+
 ## Relocation stability
 
 The central property: a PCFSIG_SIG signature remains valid across any

reference/PCF-SIG-v1.0/src/endorse.rs

@@ -0,0 +1,182 @@
+//! Pattern B helpers (spec Section 12.2 and 12.2.1): produce and embed CA
+//! endorsements of leaf PCFSIG_KEY partitions, without the CA ever touching
+//! the leaf's container file.
+//!
+//! Two stages:
+//!
+//! * **CA side** ([`issue_endorsement`]) is a pure function over a private
+//!   key plus the leaf's planned PCFSIG_KEY identity. It needs no I/O and no
+//!   container -- the stateless-server workflow W2 of spec Section 12.2.1.
+//!
+//! * **Client side** ([`embed_endorsement`]) takes the response and writes
+//!   the CA's PCFSIG_KEY and PCFSIG_SIG partitions into the local container.
+
+use std::io::{Read, Seek, Write};
+
+use pcf::{Container, HashAlgo, LABEL_SIZE, UID_SIZE};
+
+use crate::algo::KeyFormat;
+use crate::consts::*;
+use crate::error::{Error, Result};
+use crate::key::{compute_fingerprint, KeyRecord};
+use crate::manifest::{is_crypto_hash, Manifest, SignedEntry};
+use crate::sig::SignaturePartition;
+use crate::sign::SigningMaterial;
+
+/// CA-side input: everything the CA needs to compute a key endorsement
+/// without seeing the leaf's container.
+#[derive(Debug, Clone)]
+pub struct EndorsementRequest {
+    /// Leaf key's format id (spec Section 6.2).
+    pub key_format: KeyFormat,
+    /// Leaf key's raw bytes in the encoding named by `key_format`.
+    pub key_data: Vec<u8>,
+    /// PCF uid that the leaf PCFSIG_KEY partition will use in the client's
+    /// container. MUST be agreed before issuance and not changed afterwards.
+    pub intended_uid: [u8; UID_SIZE],
+    /// PCF 32-byte label field that the leaf PCFSIG_KEY partition will use.
+    pub intended_label: [u8; LABEL_SIZE],
+    /// PCF data_hash algorithm the leaf PCFSIG_KEY partition will use.
+    /// MUST be cryptographic (16, 17, or 18) per spec Section 9.
+    pub data_hash_algo: HashAlgo,
+}
+
+/// CA-side output: bytes the client embeds in its container to publish the
+/// endorsement.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct EndorsementResponse {
+    /// CA's Key Record bytes (becomes the CA PCFSIG_KEY partition data).
+    pub ca_key_record_bytes: Vec<u8>,
+    /// Assembled PCFSIG_SIG partition bytes (manifest || sig_len || sig
+    /// || trailer_len=0) ready to be added as a single PCF partition.
+    pub ca_sig_partition_bytes: Vec<u8>,
+}
+
+/// Produce a key endorsement (spec Section 12.2.1, workflow W2).
+///
+/// This function performs NO I/O: it consumes only the CA's signing key and
+/// the leaf's planned identity. It can therefore be hosted behind an
+/// HSM-fronted, stateless endpoint with no per-issuance database.
+pub fn issue_endorsement(
+    ca: &SigningMaterial,
+    request: &EndorsementRequest,
+    signed_at_unix_seconds: i64,
+) -> Result<EndorsementResponse> {
+    if !is_crypto_hash(request.data_hash_algo) {
+        return Err(Error::NonCryptoTargetHash);
+    }
+    if request.intended_uid == pcf::NIL_UID {
+        return Err(Error::EntryNilUid);
+    }
+
+    // 1. Serialise the leaf Key Record exactly as the client will write it.
+    let leaf_key_record = KeyRecord::new(request.key_format, request.key_data.clone())?.to_bytes();
+
+    // 2. Build the SignedEntry committing to the leaf PCFSIG_KEY partition's
+    //    identity and to the bytes of its Key Record.
+    let signed_entry = SignedEntry {
+        uid: request.intended_uid,
+        partition_type: TYPE_PCFSIG_KEY,
+        label: request.intended_label,
+        used_bytes: leaf_key_record.len() as u64,
+        data_hash_algo: request.data_hash_algo,
+        data_hash: request.data_hash_algo.compute(&leaf_key_record),
+    };
+
+    // 3. Build the Manifest and sign it.
+    let manifest_hash = ca
+        .sig_algo()
+        .required_manifest_hash()
+        .expect("implemented algorithms bind a manifest hash");
+    let manifest = Manifest::new(
+        ca.sig_algo(),
+        manifest_hash,
+        ca.fingerprint(),
+        signed_at_unix_seconds,
+        vec![signed_entry],
+    );
+    let manifest_bytes = manifest.to_bytes();
+    let signature = ca.sign(&manifest_bytes);
+
+    // 4. Compose the CA's Key Record and the PCFSIG_SIG partition bytes.
+    let ca_key_record_bytes = ca.to_key_record().to_bytes();
+    let ca_sig_partition_bytes = SignaturePartition {
+        manifest,
+        manifest_bytes,
+        signature,
+        trailer: Vec::new(),
+    }
+    .to_bytes();
+
+    Ok(EndorsementResponse {
+        ca_key_record_bytes,
+        ca_sig_partition_bytes,
+    })
+}
+
+/// Client-side: embed an [`EndorsementResponse`] into the local container.
+///
+/// Adds the CA's PCFSIG_KEY partition (skipped if a partition with that
+/// fingerprint is already present) and the CA's PCFSIG_SIG partition.
+pub fn embed_endorsement<S: Read + Write + Seek>(
+    container: &mut Container<S>,
+    response: &EndorsementResponse,
+    ca_key_uid: [u8; UID_SIZE],
+    ca_sig_uid: [u8; UID_SIZE],
+    ca_key_label: &str,
+    ca_sig_label: &str,
+) -> Result<()> {
+    // Refuse to duplicate an existing CA key partition.
+    let new_key = KeyRecord::from_bytes(&response.ca_key_record_bytes)?;
+    let mut ca_key_already_present = false;
+    for e in container.entries()? {
+        if e.partition_type == TYPE_PCFSIG_KEY {
+            let data = container.read_partition_data(&e)?;
+            if let Ok(existing) = KeyRecord::from_bytes(&data) {
+                if existing.fingerprint == new_key.fingerprint {
+                    ca_key_already_present = true;
+                    break;
+                }
+            }
+        }
+    }
+    if !ca_key_already_present {
+        container.add_partition(
+            TYPE_PCFSIG_KEY,
+            ca_key_uid,
+            ca_key_label,
+            &response.ca_key_record_bytes,
+            0,
+            HashAlgo::Sha256,
+        )?;
+    }
+    container.add_partition(
+        TYPE_PCFSIG_SIG,
+        ca_sig_uid,
+        ca_sig_label,
+        &response.ca_sig_partition_bytes,
+        0,
+        HashAlgo::Sha256,
+    )?;
+    Ok(())
+}
+
+/// Convenience: compute the PCF data_hash that a leaf PCFSIG_KEY partition
+/// will publish, given the same inputs the CA used. Lets a client verify
+/// locally that the EndorsementRequest it sent and the partition it intends
+/// to write agree byte-for-byte.
+pub fn expected_leaf_key_data_hash(
+    key_format: KeyFormat,
+    key_data: &[u8],
+    data_hash_algo: HashAlgo,
+) -> Result<[u8; pcf::HASH_FIELD_SIZE]> {
+    let leaf_key_record = KeyRecord::new(key_format, key_data.to_vec())?.to_bytes();
+    Ok(data_hash_algo.compute(&leaf_key_record))
+}
+
+/// Convenience: SHA-256 fingerprint of raw key bytes (spec Section 6.3).
+/// Re-exported here so client code can build an [`EndorsementRequest`]
+/// without importing `key::compute_fingerprint` directly.
+pub fn fingerprint_of(key_data: &[u8]) -> [u8; FINGERPRINT_SIZE] {
+    compute_fingerprint(key_data)
+}

reference/PCF-SIG-v1.0/src/lib.rs

@@ -49,6 +49,7 @@
 
 mod algo;
 pub mod consts;
+mod endorse;
 mod error;
 mod key;
 mod manifest;
@@ -58,6 +59,10 @@ mod verify;
 
 pub use algo::{KeyFormat, SigAlgo};
 pub use consts::*;
+pub use endorse::{
+    embed_endorsement, expected_leaf_key_data_hash, fingerprint_of, issue_endorsement,
+    EndorsementRequest, EndorsementResponse,
+};
 pub use error::{Error, Result};
 pub use key::{compute_fingerprint, KeyMetadata, KeyRecord};
 pub use manifest::{is_crypto_hash, Manifest, SignedEntry};
@@ -66,6 +71,6 @@ pub use sign::{
     ensure_key_partition, sign_partitions, signed_entry_from_partition, SigningMaterial,
 };
 pub use verify::{
-    verify_all, verify_all_with_recheck, DataRecheck, EntryReport, EntryVerdict, ManifestVerdict,
-    SignatureReport, UnverifiableReason,
+    key_endorsements, verify_all, verify_all_with_recheck, DataRecheck, EntryReport, EntryVerdict,
+    ManifestVerdict, SignatureReport, UnverifiableReason,
 };

reference/PCF-SIG-v1.0/src/verify.rs

@@ -98,6 +98,63 @@ pub enum DataRecheck {
     Recompute,
 }
 
+/// Find every signer whose Valid signature in `reports` countersigns the
+/// PCFSIG_KEY partition whose fingerprint is `leaf_key_fingerprint` (spec
+/// Section 12.2). Returns the deduplicated `signer_key_fingerprint`s of those
+/// signers, in first-seen order. Self-endorsement (a signer endorsing its own
+/// key) is filtered out as semantically vacuous.
+///
+/// The container is consulted to locate the leaf PCFSIG_KEY partition by
+/// fingerprint; if no such partition exists in the file the result is empty.
+///
+/// The reports passed in MUST come from [`verify_all`] or
+/// [`verify_all_with_recheck`] on the same container; the function does not
+/// re-verify any signatures.
+pub fn key_endorsements<S: Read + Write + Seek>(
+    container: &mut Container<S>,
+    reports: &[SignatureReport],
+    leaf_key_fingerprint: &[u8; FINGERPRINT_SIZE],
+) -> Result<Vec<[u8; FINGERPRINT_SIZE]>> {
+    // 1. Locate the leaf PCFSIG_KEY partition's PCF uid by fingerprint.
+    let entries = container.entries()?;
+    let mut leaf_key_uid: Option<[u8; UID_SIZE]> = None;
+    for e in &entries {
+        if e.partition_type == TYPE_PCFSIG_KEY {
+            let data = container.read_partition_data(e)?;
+            if let Ok(rec) = KeyRecord::from_bytes(&data) {
+                if &rec.fingerprint == leaf_key_fingerprint {
+                    leaf_key_uid = Some(e.uid);
+                    break;
+                }
+            }
+        }
+    }
+    let leaf_key_uid = match leaf_key_uid {
+        Some(u) => u,
+        None => return Ok(Vec::new()),
+    };
+
+    // 2. Scan reports for Valid signatures whose manifests cover that uid.
+    let mut endorsers: Vec<[u8; FINGERPRINT_SIZE]> = Vec::new();
+    for r in reports {
+        if !matches!(r.verdict, ManifestVerdict::Valid) {
+            continue;
+        }
+        if &r.signer_key_fingerprint == leaf_key_fingerprint {
+            // Self-endorsement is semantically empty.
+            continue;
+        }
+        let endorses = r
+            .entries
+            .iter()
+            .any(|er| er.uid == leaf_key_uid && matches!(er.verdict, EntryVerdict::Valid));
+        if endorses && !endorsers.contains(&r.signer_key_fingerprint) {
+            endorsers.push(r.signer_key_fingerprint);
+        }
+    }
+    Ok(endorsers)
+}
+
 /// Verify every PCFSIG_SIG partition in `container` and return one report
 /// each. Returns an empty vector if the container has no signatures.
 pub fn verify_all<S: Read + Write + Seek>(