# Identity Certificates * Brayden Langley () * Ty Everett () ## Abstract This specification defines identity certificates for BRC-100 wallets and peer-to-peer authentication systems. A certificate binds an identity key to encrypted certified fields under a certifier signature, while allowing the holder to reveal selected fields to selected verifiers. The specification covers the core certificate JSON and binary formats, the canonical signature preimage, certificate field encryption, master keyrings, verifier keyrings, and revocation outpoints. This specification is authoritative for certificate primitives used by [BRC-100](/brc/wallet/0100.md), [BRC-103](/brc/peer-to-peer/0103.md), and [BRC-104](/brc/peer-to-peer/0104.md). Older certificate descriptions in Authrite-era specifications, including BRC-31, BRC-53, and BRC-56, are not normative for BRC-100 certificate behavior. ## Motivation Digital signatures prove control of keys, but applications also need a privacy-preserving way to verify claims about the controller of a key. Identity certificates provide that linkage without requiring the holder to reveal every certified attribute to every verifier. The certifier signs encrypted field values, so the certificate remains tamper-evident even when no fields are revealed. The holder can later provide encrypted field-revelation keys for only the fields a verifier is allowed to inspect. ## Terminology * **Subject**: The identity key whose holder is certified. * **Certifier**: The identity key that signs the certificate. * **Verifier**: A party receiving a certificate and optionally receiving keys for selected fields. * **Core certificate**: The signed certificate fields, excluding all keyrings. * **Master certificate**: A core certificate plus a master keyring that lets the subject or certifier decrypt all certificate fields. * **Verifiable certificate**: A core certificate plus a verifier keyring that lets a specific verifier decrypt selected certificate fields. * **Field revelation key**: A random 32-byte symmetric key used to encrypt one certificate field value. * **Keyring**: A map from field names to encrypted field revelation keys. The key words "MUST", "MUST NOT", "SHOULD", and "MAY" are to be interpreted as normative requirements. ## Primitive Types | Type | JSON representation | Binary representation | Requirements | | ------------------------- | ---------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CertificateTypeID` | Base64 string | 32 bytes | Identifies the certificate type. Certificates with the same type are expected to use the same field names and meanings. | | `CertificateSerialNumber` | Base64 string | 32 bytes | Uniquely identifies a certificate from a certifier. | | `PublicKey` | Hex string | 33 bytes | Compressed secp256k1 public key. | | `RevocationOutpoint` | `.` string | 32-byte txid followed by VarInt vout | Identifies the UTXO whose spend revokes the certificate. The disabled sentinel is `0000000000000000000000000000000000000000000000000000000000000000.0`. | | `Signature` | Hex string | DER-encoded ECDSA bytes | Certifier signature over the canonical core certificate preimage. | | `CertificateFieldName` | UTF-8 string | VarInt length followed by UTF-8 bytes | 1 to 50 UTF-8 bytes. For interoperable signed certificates, field names SHOULD be printable ASCII so all implementations sort them identically. | | `CertificateFieldValue` | Base64 string | UTF-8 bytes of the Base64 string in `CertificateBinary` | Encrypted field value, encoded as Base64 for JSON and signed as that Base64 string. | | `KeyringValue` | Base64 string | Base64-decoded bytes in keyring-map binary encodings | BRC-2 encrypted field revelation key. | ## Core Certificate JSON A core certificate is a JSON object with exactly these signed members: | Field | Type | Description | | -------------------- | -------------------------------------------------------- | ---------------------------- | | `type` | `CertificateTypeID` | Certificate type identifier. | | `serialNumber` | `CertificateSerialNumber` | Certificate serial number. | | `subject` | `PublicKey` | Subject identity key. | | `certifier` | `PublicKey` | Certifier identity key. | | `revocationOutpoint` | `RevocationOutpoint` | Revocation UTXO reference. | | `fields` | map of `CertificateFieldName` to `CertificateFieldValue` | Encrypted certified fields. | | `signature` | `Signature` | Certifier signature. | Example: ```json { "type": "AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE=", "serialNumber": "AgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgI=", "subject": "024d4b6cd1361032f49d6c5cb7198fdd0458d4fd5f2d0f418da24ff2b63243a6f7", "certifier": "03531fe6068134503d846f476d6b2e3c000d70bb7c3937c8d537ef7d24c7d9e6c8", "revocationOutpoint": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef.1", "fields": { "email": "uS49rSc3jHRjmE3+/sT1Kf12p2vISiVfDX4SzsqKXWQJdVfuZJcgxjp34MBzEP9PIzK+8j7JqUs=", "name": "CSDUXeL3aMCSdWGMZmkAPq4iH0K2FfCUvYZZF/7l4hRLIgSJg+gMojGZrXJ+6qKQ" }, "signature": "304402201f0f2c2d86ad4c2271170cf967f7a9d6106d81e5b7d273decae34d284fcfced9022023cccf38074113a7e8620d9b97b860c7cb7b54805af343c03d3f44ce12da55b8" } ``` The `signature` member MUST NOT be included when computing the signature preimage. Keyrings and decrypted fields MUST NOT be included in the core certificate signature. There is no `validationKey` field in this specification. Implementations MUST verify certificates using the certifier identity key and the BRC-100 signature derivation described below. ## Certificate Binary Format `CertificateBinary` is the canonical binary form of the core certificate and the canonical signature preimage source. It is serialized in this exact order: | Order | Field | Encoding | | ----- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | 1 | `type` | 32 bytes, Base64-decoded from JSON. | | 2 | `serialNumber` | 32 bytes, Base64-decoded from JSON. | | 3 | `subject` | 33 bytes, hex-decoded from JSON. | | 4 | `certifier` | 33 bytes, hex-decoded from JSON. | | 5 | `revocationOutpoint.txid` | 32 bytes, hex-decoded txid. | | 6 | `revocationOutpoint.vout` | VarInt output index. | | 7 | `fields.count` | VarInt number of fields. | | 8 | each field | Field entries sorted by field name, each as `VarInt nameLength`, `name UTF-8 bytes`, `VarInt valueLength`, `value UTF-8 bytes`. | | 9 | `signature` | DER signature bytes, only when serializing with the signature included. | Field entries MUST be ordered lexicographically by field name before serialization. For current SDK interoperability, field values in `CertificateBinary` are the UTF-8 bytes of the Base64 string, not the Base64-decoded ciphertext bytes. Because the raw signature is the final field and is not length-prefixed in `CertificateBinary`, any enclosing binary protocol that appends extension data after a certificate MUST length-prefix the complete `CertificateBinary` first. ## Signature Creation and Verification The signature preimage is `CertificateBinary` serialized with `includeSignature = false`. The preimage MUST be hashed with SHA-256 by the BRC-100 signature method before ECDSA signing. The certifier signs using: | BRC-100 signature parameter | Value | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `protocolID` | `[2, "certificate signature"]` | | `keyID` | ` ` using the JSON Base64 strings separated by one U+0020 space | | `counterparty` | Publicly verifiable signature semantics. In current `ts-sdk`, this is produced by omitting `counterparty`, which defaults to `anyone`. | | `data` | The preimage bytes from `CertificateBinary(false)`. | A verifier verifies using: | BRC-100 verification parameter | Value | | ------------------------------ | ------------------------------------------------------------------------ | | `protocolID` | `[2, "certificate signature"]` | | `keyID` | ` ` | | `counterparty` | The certificate `certifier` public key. | | `data` | The same preimage bytes from `CertificateBinary(false)`. | | `signature` | DER signature bytes decoded from the certificate `signature` hex string. | JSON member ordering is irrelevant for signature verification. Implementations MUST NOT use stable JSON stringification as the certificate signature preimage. ## Field Encryption Each certificate field value is encrypted independently: 1. Generate a random 32-byte field revelation key `K_f`. 2. UTF-8 encode the plaintext field value. 3. Encrypt the plaintext with AES-256-GCM using `K_f`. 4. Encode the encrypted field value as `Base64(IV || ciphertext || tag)`. The IV MUST be 32 bytes. The authentication tag MUST be 16 bytes. No additional authenticated data is used by the current reference implementation. The certifier signs only the encrypted `fields` map. Plaintext field values, field revelation keys, keyrings, and decrypted field caches MUST NOT be signed as part of the core certificate. ## Keyring Encryption A keyring value is a BRC-2/BRC-100 encrypted field revelation key. The plaintext is the raw 32-byte `K_f`. The ciphertext is encoded as `Base64(IV || ciphertext || tag)` where the IV and tag follow BRC-2 encryption behavior. All certificate keyring encryption uses: | BRC-100 encryption parameter | Master keyring | Verifier keyring | | ---------------------------- | ------------------------------------- | --------------------------------------------------- | | `protocolID` | `[2, "certificate field encryption"]` | `[2, "certificate field encryption"]` | | `keyID` | `` | ` ` using one U+0020 space | | `plaintext` | Raw 32-byte field revelation key | Raw 32-byte field revelation key | For a master keyring, the encrypting party sets `counterparty` to the other party that must be able to decrypt the keyring value. In direct or certifier-issued flows, this is normally the certifier when the subject creates the encrypted fields, or the subject when the certifier creates the encrypted fields. For a verifier keyring, the subject decrypts the applicable master keyring entries and re-encrypts the raw field revelation keys with `counterparty = verifier`. The verifier decrypts those keyring entries with `counterparty = subject`. ## Master Certificates A master certificate is a core certificate plus a complete keyring that can reveal every field in `fields`. Canonical JSON extension: ```json { "type": "...", "serialNumber": "...", "subject": "...", "certifier": "...", "revocationOutpoint": "...", "fields": { "name": "..." }, "signature": "...", "masterKeyring": { "name": "..." } } ``` The `masterKeyring` member MUST contain exactly one non-empty keyring value for every field in `fields`. SDK and wallet API contexts MAY name the same data `keyringForSubject` or `keyring`; those names are aliases for the master keyring in that context and MUST NOT alter signature semantics. Before storing or accepting a master certificate, a wallet SHOULD verify: 1. The core certificate signature is valid. 2. The master keyring contains an entry for every field. 3. Every master keyring entry decrypts to a field revelation key that decrypts its corresponding encrypted field value. ## Verifiable Certificates A verifiable certificate is a core certificate plus a verifier-specific keyring for zero or more selected fields. Canonical JSON extension: ```json { "type": "...", "serialNumber": "...", "subject": "...", "certifier": "...", "revocationOutpoint": "...", "fields": { "email": "...", "name": "...", "organization": "..." }, "signature": "...", "keyring": { "email": "...", "name": "..." } } ``` The `keyring` member MUST contain only fields present in `fields`. It MAY be empty or omitted when no fields are revealed. The verifier MUST verify the core certificate signature before relying on any decrypted field. The verifier MUST decrypt only fields for which keyring entries are present. The BRC-100 `proveCertificate` result returns this verifier keyring as `keyringForVerifier`; a transmitted verifiable certificate uses `keyring`. ## Extension Binary Encodings The raw `CertificateBinary` format is the only signed binary format. Extension binary formats are unsigned envelopes for carrying keyrings next to a length-prefixed core certificate. `KeyringMapBinary`: | Order | Field | Encoding | | ----- | ------------ | ----------------------------------------------------------------------------------------------------------- | | 1 | `entryCount` | VarInt. | | 2 | each entry | `VarInt fieldNameLength`, field name UTF-8 bytes, `VarInt valueLength`, Base64-decoded keyring value bytes. | `CertificateWithKeyringBinary`: | Order | Field | Encoding | | ----- | ------------------- | ---------------------------------------------------------------------- | | 1 | `certificateLength` | VarInt length of the complete `CertificateBinary` including signature. | | 2 | `certificate` | `CertificateBinary`. | | 3 | `keyring` | `KeyringMapBinary`. | The same envelope is used for master certificates and verifiable certificates; the interpretation of the keyring is determined by context. When the keyring is absent, protocols SHOULD transmit the raw `CertificateBinary` rather than an empty envelope. BRC-100 wallet-wire methods use method-specific envelopes around the same primitives. For example, `proveCertificate` submits a core certificate structure and receives a `KeyringMapBinary`; `listCertificates` length-prefixes each certificate and may append a keyring flag, keyring map, and verifier value. Those wallet-wire envelopes do not change the BRC-52 core certificate format. ## Certificate Acquisition and Revelation ### Direct Acquisition In direct acquisition, a wallet receives a signed core certificate and a master keyring from a certifier or other keyring revealer. The wallet MUST set or confirm `subject` as its own identity key before storage. The wallet MUST verify the signature and confirm that the master keyring decrypts the fields before storing the certificate. ### Issuance Acquisition In issuance acquisition, the subject prepares encrypted fields and a master keyring for the certifier, then sends the encrypted fields to the certifier for signing. The certifier returns a signed core certificate. The subject stores the returned certificate with the master keyring it generated, after verifying that the returned type, subject, certifier, fields, serial number derivation, revocation outpoint, and signature are acceptable for the issuance protocol being used. ### Selective Revelation To reveal fields to a verifier: 1. The subject locates the stored master certificate. 2. The subject verifies the requested field names are a subset of the certificate fields. 3. The subject decrypts each requested master keyring value to recover `K_f`. 4. The subject re-encrypts each `K_f` for the verifier using the verifier keyring parameters above. 5. The subject returns the verifier keyring, either as a `keyringForVerifier` result or embedded in a verifiable certificate as `keyring`. ## Revocation The `revocationOutpoint` points to a UTXO controlled according to the certifier's revocation policy. If that UTXO has been spent, the certificate MUST be treated as revoked. If the disabled sentinel `0000000000000000000000000000000000000000000000000000000000000000.0` is used, UTXO-based revocation is disabled and verifiers MUST rely on the policy for that certificate type. Certifiers SHOULD publish clear rules for revocation monitoring, reissuance, and key compromise handling. If a certifier identity key is compromised, the certifier SHOULD revoke affected certificates and reissue under a new certifier identity key. ## Implementation Basis This revision is grounded in the reference behavior of the BSV SDK and Wallet Toolbox certificate implementations, including: * `Certificate`, `MasterCertificate`, and `VerifiableCertificate` behavior in `bsv-blockchain/ts-sdk`. * Certificate lifecycle, wallet storage, `acquireCertificate`, `listCertificates`, and `proveCertificate` behavior in `bsv-blockchain/wallet-toolbox`. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://hub.bsvblockchain.org/brc/peer-to-peer/0052.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.