sansid 0.1.0

Anonymous age verification with BBS+ proofs and blind issuance
Documentation
# SansID v1 protocol

This document defines the fixed Rust reference profile implemented by this repository.

## Fixed profile

| Item | Value |
| --- | --- |
| Protocol version | `sansid/1` |
| Signature system | BBS+ proof of knowledge over BLS12-381 |
| Hash | SHA-512 |
| Public parameters | Deterministically derived from `SansID BBS+ public parameters v1` |
| Schema | `org.sansid.age-over-18/1` |
| Predicate | `age_over_18` |
| Challenge nonce | exactly 32 random bytes |
| Transport encoding | JSON with unpadded base64url for binary values |

The profile accepts no algorithm negotiation. A different cryptographic profile requires a new protocol version, independent review, new test vectors, and a distinct wire identifier.

## Credential messages

The issuer signs exactly three scalar messages in this order:

| Index | Value | Disclosure |
| --- | --- | --- |
| 0 | `HashToScalar("SansID holder secret scalar v1", holder_secret)` | hidden |
| 1 | `HashToScalar("SansID credential schema scalar v1", schema)` | revealed |
| 2 | `HashToScalar("SansID predicate scalar v1", "age_over_18")` | revealed |

`holder_secret` is 32 bytes generated from the operating-system random source and is never serialized by the reference API. The two revealed messages are global constants and do not identify a holder.

## Blind issuance

The issuer begins one issuance session with a fresh 32-byte `IssuanceChallenge` and retains it as one-time server-side state. The holder computes a Pedersen commitment to the hidden message at index 0 with a fresh signature blinding. It also creates a Schnorr proof of knowledge for both the holder-secret scalar and that blinding.

The issuance proof transcript binds the fixed profile, schema, issuer key and identifier, issuance challenge, commitment, commitment bases, and proof commitment. The issuer verifies this proof before signing the holder commitment together with the schema and predicate. The holder unblinds the returned BBS+ signature and verifies it locally.

This prevents the issuer from receiving the holder secret during issuance. The issuer must still use its own policy to ensure that it only issues after a valid real-world age check.

## Public parameters and issuer keys

BBS+ public parameters are deterministically derived from the fixed label and support exactly three messages. The parameter derivation avoids issuer-selected generators and makes the parameter set reproducible by every participant.

An issuer key is serialized using Arkworks canonical compressed encoding. Its SansID key identifier is:

```text
base64url(SHA-512(length(KEY_ID_LABEL) || KEY_ID_LABEL || length(key_bytes) || key_bytes))
```

The issuer key inside a presentation is informational. The verifier must compare it with a key from its issuer trust configuration before proof verification.

## Proof request

The verifier backend creates:

```json
{
  "origin": "https://site.example",
  "predicate": "age_over_18",
  "nonce": "base64url of exactly 32 random bytes"
}
```

`origin` is a canonical HTTPS origin with no credentials, path, query, or fragment. The backend stores the request state and permits one successful nonce consumption only.

## Presentation

The holder returns:

```json
{
  "protocol_version": "sansid/1",
  "ciphersuite": "BBS+-BLS12-381-SHA-512-SANSID-1",
  "schema": "org.sansid.age-over-18/1",
  "predicate": "age_over_18",
  "origin": "https://site.example",
  "nonce": "base64url",
  "issuer_key_id": "base64url",
  "issuer_public_key": "base64url canonical public key",
  "proof": "base64url canonical BBS+ proof"
}
```

Before decoding cryptographic values, implementations reject JSON larger than 8192 bytes, public keys larger than 256 bytes, and proofs larger than 2048 bytes. Decoders require canonical compressed encoding and reject trailing bytes.

## Transcript

The Fiat-Shamir challenge is formed from length-prefixed fields. Each field is encoded as an unsigned 64-bit big-endian length followed by its bytes. The prefix is:

```text
TRANSCRIPT_LABEL
protocol_version
ciphersuite
schema
issuer_key_id
canonical_issuer_public_key
origin
predicate
nonce
```

The implementation appends the BBS+ proof challenge contribution, which includes the randomized proof values, public parameters, and the two revealed scalar messages. It hashes the completed transcript into the BLS12-381 scalar field using the `schnorr_pok` random-oracle helper with SHA-512.

## Verification requirements

The verifier must reject a presentation unless all of the following are true:

1. The fixed profile fields match exactly.
2. The origin, predicate, and nonce match the request it generated.
3. The nonce has not already been consumed.
4. The issuer public key and key identifier match a configured trusted issuer key.
5. The BBS+ proof verifies with the recomputed transcript challenge.

The cryptographic library used here implements BBS+ from the Camenisch, Drijvers, and Lehmann construction. This profile does not claim wire compatibility with the active IETF BBS draft. The implementation freezes its current profile to prevent silent cross-protocol interpretation.