How to Implement Selective Disclosure Mechanisms for Citizen Health Records

Selective disclosure is a privacy-enhancing mechanism that allows an individual to prove specific claims derived from a credential without revealing the entire document. For citizen health records, this means a person can prove they are over 18, have a valid vaccination, or meet a specific lab result threshold, while keeping all other personal health information confidential. This is a fundamental shift from the current model of sharing entire PDFs or database entries, moving towards data minimization and user sovereignty. Implementing this requires a stack of cryptographic primitives, including digital signatures, hash functions, and zero-knowledge proof systems like zk-SNARKs or Bulletproofs.

The core architecture relies on Verifiable Credentials (VCs), a W3C standard for tamper-evident credentials that can be cryptographically verified. A health authority, acting as an issuer, signs a VC containing the citizen's health data. This signed credential is stored in a digital wallet controlled by the citizen. When a verifier (e.g., an event organizer or employer) requests proof of a specific claim, the wallet uses a zero-knowledge proof (ZKP) protocol to generate a proof. This proof cryptographically demonstrates that the signed VC contains the required claim (e.g., vaccinationStatus == "complete") and that the signature is valid, without disclosing the VC's other attributes or the citizen's identity.

For developers, implementation involves several key steps. First, define the credential schema using a framework like Hyperledger AnonCreds or JSON-LD with BBS+ signatures. This schema structures the data (e.g., birthDate, lastTestResult). The issuer then creates and signs the credential. The critical component is the presentation request from the verifier, which specifies the exact claims and predicates needed (e.g., "Prove your last HbA1c test result was less than 6.5%"). The prover's wallet software uses a ZKP library, such as snarkjs for Circom circuits or arkworks for R1CS, to generate a proof that satisfies this request against the held credential.

A practical example using JSON Web Tokens (JWT) and JSON Web Proofs (JWP) illustrates a simpler, non-zero-knowledge approach. The issuer creates a JWT containing the health data. For selective disclosure, the prover can create a JWP Selective Disclosure (SD-JWT), which uses hash-based disclosures to allow the verifier to check only the revealed claims. While this doesn't offer the full privacy of ZKPs, it's a standardized and simpler-to-implement method for many use cases. Code snippets for issuing an SD-JWT and creating a presentation are readily available in libraries like sd-jwt-js.

Security and trust are paramount. The system's trust model is decentralized: trust is placed in the issuer's cryptographic signature, not a central database. Developers must ensure private key security for issuers and wallets, implement proper revocation mechanisms (like credential status lists), and conduct thorough audits of any ZKP circuits. The end result is a system that enhances privacy, reduces data breach risks, and empowers citizens with provable ownership of their most sensitive personal information, aligning with regulations like GDPR and HIPAA through technological enforcement.

Selective disclosure is built on zero-knowledge cryptography and verifiable credentials. You should understand core concepts like digital signatures (e.g., EdDSA, BBS+), hash functions (e.g., SHA-256), and public-key infrastructure (PKI). Familiarity with JSON-LD and the W3C Verifiable Credentials Data Model is crucial, as they define the standard structure for credentials and presentations. For health data specifically, knowledge of interoperability standards like FHIR (Fast Healthcare Interoperability Resources) or HL7 is highly recommended to model clinical information correctly.

You will need a development environment capable of handling cryptographic operations. For JavaScript/TypeScript projects, libraries like @digitalbazaar/ed25519-signature-2020 and @mattrglobal/bbs-signatures provide essential signing capabilities. The Decentralized Identity Foundation (DIF) maintains the did-resolver and universal-resolver libraries for working with Decentralized Identifiers (DIDs). A basic understanding of DID methods (like did:key, did:web, or did:ion) and their associated Verifiable Data Registries is necessary for issuing and verifying credentials.

For practical implementation, you must define your credential schema. This schema, often published as a JSON Schema on a trusted platform like the Schema.org or a blockchain, dictates the structure of the health data claims (e.g., birthDate, vaccinationStatus). You'll also need to design the presentation request, which specifies exactly which claims a verifier needs and the cryptographic proofs required. Setting up a test network or a local blockchain (like Ganache for Ethereum) is advisable for experimenting with on-chain registry patterns without cost.

Finally, consider the privacy and regulatory landscape. Implementing health record systems requires strict adherence to regulations like HIPAA in the US or GDPR in the EU. Your design must incorporate data minimization by default, ensuring the selective disclosure mechanism only reveals the absolute minimum necessary information. Understanding key management strategies for holders and issuers is also a critical security prerequisite before moving to production.

Selective disclosure is a cryptographic principle that allows a user to prove a specific claim derived from a credential without revealing the credential itself. For citizen health records, this means a patient can prove they are over 18, have a valid vaccination, or possess a certain blood type without exposing their full medical history. This architecture moves beyond the all-or-nothing data sharing of traditional systems, enabling privacy-by-design and user sovereignty. Core components include a verifiable data registry (like a blockchain for DIDs), issuers (hospitals, labs), holders (patients with digital wallets), and verifiers (employers, event venues).

The implementation relies on W3C Verifiable Credentials (VCs) and Decentralized Identifiers (DIDs). A health authority issues a signed VC to a patient's wallet, containing attested claims (e.g., "covidVaccinationStatus": "fullyVaccinated"). The credential is cryptographically bound to the patient's DID. When proof is required, the holder generates a Verifiable Presentation (VP). Using zero-knowledge proof (ZKP) systems like zk-SNARKs or BBS+ signatures, the presentation can be crafted to only reveal the necessary predicate (e.g., vaccinationStatus == true) while keeping all other data and the credential's signature hidden.

For on-chain verification, a verifier smart contract is essential. This contract holds the public verification key of the issuer and the logic for the required claim. The patient submits their ZKP to the contract. The contract verifies the proof cryptographically, confirming the claim is valid and signed by a trusted issuer, without learning any other information. On Ethereum, this can be implemented using libraries like snarkjs with Groth16 or PLONK proving schemes, or using Semaphore for anonymous group membership proofs. Off-chain, verifiers can use lighter-weight BBS+ signature proofs.

A practical architecture involves a backend issuance service that signs VCs, a holder wallet (mobile or web) that stores credentials and generates proofs, and a verification service/contract. Data formats should follow the W3C VC Data Model. For interoperability, use JSON-LD with linked data proofs or JWT-based VCs. Key management is critical: issuer keys must be secured in HSMs, while holder keys should be in secure enclaves or hardware wallets to prevent credential theft.

Considerations for production include revocation mechanisms like status lists or accumulator-based schemes, schema management for standardizing health data claims, and gas optimization for on-chain ZKP verification. Frameworks like Hyperledger Aries provide agents and protocols for issuing and presenting VCs, while Circom and Halo2 are used for writing custom ZKP circuits. This architecture ensures compliance with regulations like GDPR by providing data minimization, giving citizens control over their most sensitive personal information.

Selective disclosure is a core feature of Verifiable Credentials (VCs) that allows a holder to prove specific claims from a credential without revealing the entire document. For a citizen health record, this means a patient could prove they are over 18 or have a specific vaccination status without exposing their full medical history, address, or other identifiers. This is typically achieved using cryptographic techniques like BBS+ signatures or zero-knowledge proofs (ZKPs), which enable predicate proofs (e.g., "age >= 18") and selective claim revelation. The W3C Verifiable Credentials Data Model provides the standard framework for implementing these mechanisms.

The issuer, such as a national health service, must first establish its digital identity and signing capability. This involves creating a Decentralized Identifier (DID) and publishing the associated DID Document to a verifiable data registry like a blockchain or the ION network. The DID Document contains the public keys used for signing credentials. Using a library like veramo or aries-framework-javascript, you generate a key pair and register the DID. For example, creating a DID linked to the ethr provider on Ethereum: const identifier = await agent.didManagerCreate({ provider: 'did:ethr', kms: 'local' });. This establishes the issuer's cryptographically verifiable authority.

With the DID in place, the issuer defines the credential schema. This JSON Schema specifies the structure of the health record, including all possible claims like fullName, dateOfBirth, vaccinationStatus, and bloodType. The schema itself is published, often using a schema registry or by anchoring its hash on-chain, to allow verifiers to check credential structure. The actual credential is then issued by creating a signed JWT or JSON-LD proof. Crucially, to enable selective disclosure, the signing process must use a derivable proof scheme. With BBS+, you sign the entire credential but the signature allows derived proofs for subsets of claims.

Here is a conceptual code snippet for issuing a signable credential payload with veramo, preparing it for selective disclosure. Note that full BBS+ implementation may require additional plugins.

javascriptCopy
const verifiableCredential = await agent.createVerifiableCredential({
  credential: {
    issuer: { id: issuerDID },
    credentialSubject: {
      id: patientDID,
      fullName: "Jane Doe",
      dateOfBirth: "1990-01-01",
      vaccinationStatus: "Complete",
      bloodType: "O+"
    },
    credentialSchema: {
      id: "schema-id-123",
      type: "JsonSchemaValidator2018"
    }
  },
  proofFormat: 'lds', // Linked Data Signatures for ZKP compatibility
  save: false
});

The issued credential is delivered to the patient's digital wallet, which holds the private keys. The wallet software uses cryptographic libraries to perform the selective disclosure. When a verifier (e.g., an event venue) requests proof of age, the wallet generates a derived verifiable presentation. It creates a new proof, valid only for the revealed claim dateOfBirth and the predicate age >= 18, while keeping fullName and bloodType hidden. This presentation is sent to the verifier, who can validate the signature against the issuer's public DID Document without learning any extra information, fulfilling the principle of data minimization.

For production systems, issuers must carefully manage key rotation and revocation. A revocation registry, such as one defined by the W3C Status List 2021 specification, allows the issuer to invalidate credentials without compromising the privacy of holders. Furthermore, the choice of proof type (BBS+ vs. CL signatures) impacts interoperability and wallet support. Testing should involve verifying derived presentations using standard libraries to ensure the selective disclosure mechanism works correctly end-to-end before deploying for citizen use.

Selective disclosure allows a Holder to share only the necessary information from their health record credential. For instance, to verify age for a vaccination clinic, they can prove they are over 18 without revealing their exact birthdate, full name, or medical history. This is achieved using cryptographic zero-knowledge proofs (ZKPs) or signature-derived presentations, depending on the credential format. The W3C Verifiable Credentials Data Model defines this process, ensuring interoperability across different systems.

For credentials using BBS+ signatures (common in health contexts for their ZKP capabilities), the Holder uses a presentation request from the Verifier as a blueprint. This request specifies which claims are required (e.g., "vaccinationStatus": true) and which are optional. The Holder's wallet software then generates a cryptographic proof that the signed credential contains those claims, without disclosing the signature on the undisclosed attributes. Libraries like @mattrglobal/bbs-signatures provide the core APIs for this.

Here is a simplified code example using a hypothetical SDK to create a selective presentation from a health credential:

javascriptCopy
// Holder receives a presentation request from the Verifier
const presentationRequest = {
  id: "vaccine-clinic-request-123",
  query: [{
    type: "HealthPassCredential",
    required: ["vaccinationStatus"],
    optional: ["lastTestDate"]
  }]
};

// Holder selects their stored credential and creates a presentation
const selectedCredential = await wallet.getCredential("healthPass123");
const presentation = await sdk.createPresentation({
  credential: selectedCredential,
  request: presentationRequest,
  discloseFields: ["vaccinationStatus"] // Only proves this one field
});

// The `presentation` object now contains a minimal, verifiable proof.

The generated Verifiable Presentation is a new, signed data structure containing the disclosed claims and the proof. It is sent back to the Verifier (the clinic). Critically, the presentation does not contain the original credential in full, protecting the Holder's data minimization principle. The Verifier can cryptographically verify that the presented claims were issued by a trusted Issuer (e.g., the Department of Health) and have not been tampered with, all while learning nothing about the Holder's other health data.

For JSON Web Token (JWT) based credentials, selective disclosure often uses JSON Web Proof (JWP) or Selective Disclosure JWTs (SD-JWT). The SD-JWT standard (IETF RFC 9479) is particularly relevant for health records, as it allows the Holder to disclose specific JSON object properties. The Issuer provides a credential with disclosure digests alongside the signed JWT; the Holder reveals only the digests corresponding to the data they choose to share.

Implementing this correctly is vital for compliance with regulations like GDPR and HIPAA, which mandate data minimization. When building a health app, integrate a verifiable credentials wallet SDK (e.g., SpruceID's didkit, Microsoft's Verifiable Credentials SDK) that supports BBS+ or SD-JWT. Always audit the presentation request for excessive data demands and ensure the UI clearly informs the user exactly what they are about to disclose.

The verifier's core task is to check the validity of the Zero-Knowledge Proof (ZKP) presented by the citizen. This proof asserts that the citizen's hidden health data satisfies specific conditions, like being over 18 or having a certain vaccination status. The verifier does this by running a verification algorithm against the proof, the public parameters of the system, and the public inputs (the disclosed claims). The algorithm uses the proof to verify the mathematical relationship between the public data and the hidden private data, confirming its correctness without revealing anything else. This process is typically fast and requires minimal computational resources.

For a practical implementation, a verifier would use a library like snarkjs for Groth16 or circom for PLONK. The code snippet below shows a simplified verification flow in a Node.js environment, assuming the proof and public signals have been received from the prover (the citizen's wallet). The critical function verifyProof checks the proof against the verification key (a trusted public parameter generated during the trusted setup) and the public inputs.

javascriptCopy
import { verifyProof } from 'snarkjs';

async function verifyHealthProof(proof, publicSignals) {
  const vKey = await fetch("./verification_key.json"); // Load the verification key
  
  const res = await verifyProof(vKey, publicSignals, proof);
  
  if (res === true) {
    console.log("Proof is VALID. Citizen's claim is verified.");
    // Grant access or proceed with service
  } else {
    console.log("Proof is INVALID. Claim rejected.");
    // Deny request
  }
}

The public signals are crucial. These are the non-sensitive data points explicitly shared for verification, such as "isAdult: true" or "vaccinationStatus: 1". They must match exactly what the prover committed to when generating the proof. Any mismatch will cause verification to fail. It's the verifier's responsibility to define the logic these signals represent. For instance, receiving isAdult: true might trigger access to a restricted medical trial portal. The trust in this system stems from the cryptographic soundness of the zk-SNARK circuit; if it verifies, the statement is true with near-certain probability.

In a production health records system, this verification would be integrated into a backend service API. A hospital's appointment system could expose a /verify-proof endpoint. When a citizen attempts to book an age-restricted procedure, their wallet app would send the ZKP and public signals to this endpoint. The service runs the verification and returns a boolean result, seamlessly integrating privacy-preserving checks into existing workflows. This architecture decouples sensitive data storage (on the citizen's device or a decentralized identifier) from the service logic, significantly reducing the verifier's data liability and breach risk.

Key considerations for verifiers include circuit and key management. The verification key must correspond to the exact circuit used to generate the proof. Using an incorrect or compromised key invalidates the entire process. Verifiers should obtain these keys from a reputable, audited source, often the same entity that published the circuit logic for health credentials. Furthermore, the verification logic must be periodically reviewed to ensure the public signals still enforce the intended policy, as medical guidelines and legal requirements evolve over time.

BBS+ (Boneh-Boyen-Shacham Plus) is a cryptographic signature scheme that supports signature proofs of knowledge. This enables a user to derive a zero-knowledge proof from a signed credential, proving only a subset of the signed attributes. For a citizen health record, this means a patient can prove they are over 18 or have a specific vaccination status without disclosing their name, address, or other sensitive data. The core property is unlinkability: multiple proofs derived from the same signature cannot be linked together or to the original credential.

The process begins with a trusted issuer, like a hospital, signing a user's credential. This credential contains multiple attributes (e.g., name, dateOfBirth, vaccineStatus, patientId). The issuer uses their private key and the user's public key (or a commitment) to generate a BBS+ signature over the entire attribute set. In code, this involves creating cryptographic commitments to each attribute and generating a signature using pairing-friendly elliptic curves, typically BLS12-381. Libraries like @mattrglobal/bbs-signatures provide these primitives.

To create a selective disclosure proof, the user (the prover) decides which attributes to reveal (e.g., vaccineStatus) and which to keep hidden (e.g., name, patientId). They use the original signature, the disclosed attribute values, and the indices of the hidden attributes to generate a BBS+ proof. This proof cryptographically demonstrates that the disclosed attributes are part of a valid, issuer-signed set, without leaking any information about the hidden attributes. The verifier only needs the issuer's public key, the disclosed attributes, and the proof.

Here is a simplified code snippet using a hypothetical BBS+ library. Note that real implementations require careful management of cryptographic parameters.

javascriptCopy
// User creates a proof revealing only the 'vaccineStatus' (attribute index 2)
const proof = await bbs.createProof({
  signature: originalBbsSignature,
  publicKey: issuerPublicKey,
  messages: fullAttributeSet, // [name, dob, vaccineStatus, patientId]
  revealed: [2], // Indices of attributes to disclose
});
// The verifier checks the proof
const isVerified = await bbs.verifyProof({
  proof: proof,
  publicKey: issuerPublicKey,
  messages: disclosedMessages, // Only ['Fully Vaccinated']
  revealed: [2],
});

For a health record system, this mechanism enables privacy-preserving verification scenarios. A pharmacy could verify a customer's vaccination status for travel, an employer could confirm a "fitness for work" clearance, or a research study could verify participant age brackets—all without collecting full identity data. This reduces data breach risks and aligns with regulations like GDPR and HIPAA by enforcing data minimization. The cryptographic guarantee ensures the disclosed data is authentic and unaltered.

When implementing, key considerations include choosing a well-audited library (e.g., from MATTR or DIF), securely managing the issuer's private key, and defining a robust schema for attributes. Performance is also a factor, as proof generation and verification are computationally heavier than standard signatures. However, for high-stakes health data, the trade-off for enhanced user privacy and control is often justified. This pattern is foundational for verifiable credentials and decentralized identity ecosystems.

Selective disclosure transforms static health data into a dynamic, user-controlled asset. By implementing Verifiable Credentials (VCs) with BBS+ signatures or CL signatures, you enable patients to prove specific claims—like vaccination status or age—without revealing their entire medical history. The core components are the Issuer (health authority), Holder (patient wallet), and Verifier (clinic). This architecture, built on decentralized identifiers (DIDs) and standards from the W3C Verifiable Credentials Data Model, ensures data minimization and cryptographic trust.

Your next step is to choose and test a cryptographic suite. For complex, predicate-based proofs (e.g., "age > 18"), BBS+ is the current standard, with libraries like @mattrglobal/bbs-signatures. For simpler, single-attribute disclosures, CL signatures or JSON Web Tokens (JWTs) with selective disclosure may suffice. Integrate this with a wallet SDK such as Trinsic, Veramo, or Affinidi to handle credential storage and presentation for end-users. Always conduct a security audit on your credential schema and revocation mechanism.

Finally, consider the broader ecosystem. How will your system interact with existing health IT infrastructure like FHIR (Fast Healthcare Interoperability Resources)? Explore projects like DIDComm for secure, peer-to-peer messaging between wallets and verifiers. For persistent, on-chain attestations, you might anchor credential status lists or DID documents to a blockchain like Ethereum or Hyperledger Indy. The goal is not just technical implementation, but creating a usable system that respects patient autonomy while meeting regulatory requirements like GDPR and HIPAA.