Skip to content

Reveal the value (BBS)

View Markdown

Use this when the verifier needs to see a value exactly as an issuer signed it, such as “country = NZ” or “licence class = B”, and should learn nothing about the other attributes.

An issuer signs a list of attributes once with BBS, a signature scheme built for credentials. The holder can then show any subset of the attributes, together with a proof that the issuer signed the whole list. Hidden attributes stay hidden, and two presentations of the same credential can’t be linked by the proof alone.

BBS · step 1 / 5
IssuerKYC provider
issuer public keyPUBLIC0x393b…1ac6
One BBS signature over all five
  1. givenName
  2. dob
  3. country
  4. kycLevel
  5. docHash

No circuit and no trusted setup.

HolderAlice's wallet
0 · givenNameAlice Example████████REVEALEDSECRETHIDDEN
1 · dob1990-05-01████████REVEALEDSECRETHIDDEN
2 · countryUSA████████REVEALEDSECRETHIDDEN
3 · kycLevelverified████████REVEALEDSECRETHIDDEN
4 · docHash0x7d2e…a91c████████REVEALEDSECRETHIDDEN
π0x762c…e02cnew bytes each time
Verifierapp or Cardano validator
Policycountry is allowedkycLevel = verified
challenge (fresh, single-use)PUBLIC0x9ac9…9aa1
Presentation received
  • givenNameAlice Examplehidden, but signed
  • dob1990-05-01hidden, but signed
  • countryUSAhidden, but signed
  • kycLevelverifiedhidden, but signed
  • docHash0x7d2e…a91chidden, but signed
proof valid for the issuer keychallenge is new, now marked usedchallenge already used: rejectedpolicy meton Cardano, BbsKycClaimValidator pays the voucher

1. Issue

The KYC provider checks Alice's documents once and signs all five attributes as one BBS credential. Alice keeps it in her wallet.

2. Challenge

The verifier sends a fresh random challenge. The verifier picks it, never the holder, so a presentation made for this verifier can't be replayed elsewhere.

3. Present

Alice's wallet derives a presentation that reveals only the attributes she ticks, bound to the challenge. It proves the hidden attributes were signed too, without showing them. Each presentation has new proof bytes, so two verifiers can't link them. Try ticking other attributes.

4. Verify

The verifier checks the proof against the issuer's public key, checks that the challenge is one it issued and hasn't seen, then applies its policy. On Cardano, a validator runs the same BBS check natively and releases a voucher.

5. Replay

Someone resends the same presentation. Its challenge was already used, so it's rejected. On-chain, the challenge is derived from the voucher UTxO, which is already spent.

SECRET stays in the walletREVEALED the verifier sees the valueHash values are illustrative.
PartyLearns
IssuerEverything, once, at issuance
HolderTheir own credential
VerifierThe revealed attributes, and that the issuer signed them
Everyone elseNothing, unless the presentation is published (for example in a Cardano transaction, where revealed values become public)
RevealCountry.java (core)
import org.zeroj.bbs.BbsKeyPair;
import org.zeroj.bbs.BbsPresentation;
import org.zeroj.bbs.BbsService;
import org.zeroj.bbs.BbsSignature;
BbsService bbs = BbsService.pureJava();
// Issuer: sign five attributes once (keyMaterial: at least 32 secret random bytes)
BbsKeyPair issuer = bbs.keyPair(keyMaterial, keyInfo);
List<byte[]> attributes = List.of(name, dob, country, kycLevel, docId);
BbsSignature signature = bbs.sign(issuer.secretKey(), issuer.publicKey(), attributes, header);
// Holder: reveal country (2) and kycLevel (3), bound to the verifier's fresh challenge
BbsPresentation presentation = bbs.derivePresentation(
issuer.publicKey(), signature, attributes, header, challenge, new int[] {2, 3});
// Verifier: check the proof, then that the challenge is the one it issued, then its policy
boolean valid = bbs.verifyPresentation(issuer.publicKey(), presentation);

The complete, runnable program, plus key handling, headers and on-chain verification, is in the BBS guide.

  • Reusable KYC. Do identity checks once; show each service only the country and KYC level. (use case, demo reusable-kyc)
  • Professional licences. A doctor shows “licensed physician, valid until 2027” to a pharmacy portal, without a home address or registration number.
  • Event and membership passes. A member shows “tier = gold” to get in, and nothing else.
  • Supply-chain certificates. A shipper reveals “origin = EU” and “certified organic” from an auditor-signed product credential.
  • The verifier needs a fact, not the value. “Over 21” shouldn’t reveal a birth date. Use Prove a rule.
  • The value lives on-chain and changes, like a balance. BBS signs a fixed credential; use Hide a number.
  • A rare revealed value identifies the person. A unique combination of attributes can re-identify someone; reveal the minimum.
  • Replay. A presentation stays valid forever. The verifier must pick a fresh challenge and mark it used, or derive it from the UTxO being spent on-chain.
  • On-chain shape. ZeroJ’s on-chain BBS verifier supports one fixed shape: a five-attribute credential revealing positions 2 and 3, at about 2.43 billion CPU steps.
  • Maturity. BBS is Beta and follows an IRTF draft, not yet an RFC. The default pure-Java provider isn’t constant-time, so prefer the blst provider for issuer keys.