LogoLogo
  • README
  • Contribute
    • Discuss on Github
  • Example
    • Banana-Powered Bitcoin Wallet Control Protocol
  • Apps
    • The deployment-info.json Specification
  • Wallet
    • Transaction Creation
    • Data Encryption and Decryption
    • Digital Signature Creation and Verification
    • Input Redemption
    • HTTP Wallet Communications Substrate
    • XDM Wallet Communications Substrate
    • Window Wallet Communication Substrate
    • Wallet Transaction Output Tracking (Output Baskets)
    • Submitting Received Payments to a Wallet
    • Certificate Creation and Revelation
    • Unified Abstract Wallet-to-Application Messaging Layer
    • Transaction Labels and List Actions
    • Output Basket Removal and Certificate Deletion
    • Group Permissions for App Access
    • Extensible Proof-Type Format for Specific Key Linkage Claims
    • P Protocols: Allowing future wallet protocol permission schemes
    • P Baskets: Allowing Future Wallet Basket and Digital Asset Permission Schemes
    • Unified, Vendor-Neutral, Unchanging, and Open BSV Blockchain Standard Wallet-to-Application Interface
  • Transactions
    • Everett-style Transaction Envelopes
    • Simplified Payment Verification
    • Merkle proof standardised format
    • TSC Proof Format with Heights
    • Raw Transaction Format
    • TXO Transaction Object Format
    • Transaction Extended Format (EF)
    • Merkle Path JSON format
    • Compound Merkle Path Format
    • Background Evaluation Extended Format (BEEF) Transactions
    • Simplified Payment Verification
    • Merkle Path Binary Format
    • BSV Unified Merkle Path (BUMP) Format
    • Graph Aware Sync Protocol
    • Scalable Transaction Processing in the BSV Network
    • Atomic BEEF Transactions
    • BEEF V2 Txid Only Extension
  • Scripts
    • Bitcoin Script Binary, Hex and ASM Formats
    • Bitcoin Script Assembly Language
    • Pay to Public Key Hash
    • Pay to R Puzzle Hash
    • Pay to False Return
    • Pay to True Return
    • Push TX
    • Bare Multi-Signature
    • Pay to Push Drop
  • Tokens
    • There is no BRC-20
    • Definition of UTXOs as Bitcoin Tokens
    • Token Exchange Protocol for UTXO-based Overlay Networks
    • Mandala Token Protocol
  • Overlays
    • Overlay Network Data Synchronization
    • Confederacy Host Interconnect Protocol (CHIP)
    • Overlay Network Lookup Services
    • Confederacy Lookup Availability Protocol (CLAP)
    • Universal Hash Resolution Protocol
    • Overlay Network Transaction History Tracking
    • Private Overlays with P2PKH Transactions
    • Standardized Naming Conventions for BRC-22 Topic Managers and BRC-24 Lookup Services
    • Overlay Services Synchronization Architecture
    • Diverse Facilitators and URL Protocols for SHIP and SLAP Overlay Advertisements
  • Payments
    • Direct Payment Protocol (DPP)
    • Paymail Payment Destinations
    • Simple Authenticated BSV P2PKH Payment Protocol
    • PacketPay HTTP Payment Mechanism
    • Hybrid Payment Mode for DPP
    • HTTPS Transport Mechanism for DPP
    • Paymail BEEF Transaction
    • HTTP Service Monetization Framework
  • Peer-to-Peer
    • Authrite Mutual Authentication
    • PeerServ Message Relay Interface
    • PeerServ Host Interconnect Protocol
    • Identity Certificates
    • Genealogical Identity Protocol
    • Publishing Trust Anchor Details at an Internet Domain
    • Message Signature Creation and Verification
    • Serialization Format for Portable Encrypted Messages
    • Defining a Scalable IPv6 Multicast Protocol for Blockchain Transaction Broadcast and Update Delivery
    • Proven Identity Key Exchange (PIKE)
    • Peer-to-Peer Mutual Authentication and Certificate Exchange Protocol
    • HTTP Transport for BRC-103 Mutual Authentication
  • Key Derivation
    • BIP32 Key Derivation Scheme
    • BSV Key Derivation Scheme (BKDS)
    • Security Levels, Protocol IDs, Key IDs and Counterparties
    • Admin-reserved and Prohibited Key Derivation Protocols
    • Revealing Key Linkages
    • Protecting BRC-69 Key Linkage Information in Transit
    • Mnemonic For Master Private Key
    • Linked Key Derivation Scheme
    • Bidirectionally Authenticated Derivation of Privacy Restricted Type 42 Keys
    • Limitations of BRC-69 Key Linkage Revelation
    • Verifiable Revelation of Shared Secrets Using Schnorr Protocol
  • Outpoints
    • Format for Bitcoin Outpoints
    • Spending Instructions Extension for UTXO Storage Format
  • Opinions
    • Users should never see an address
    • List of user experiences
    • Legitimate Uses for mAPI
    • Security and Scalability Benefits of UTXO-based Overlay Networks
    • Improving on MLD for BSV Multicast Services
    • Web 3.0 Standard (at a high level)
    • Thoughts on the Mandala Network
    • Outputs, Overlays, and Scripts in the Mandala Network
  • State Machines
    • Simplifying State Machine Event Chains in Bitcoin
Powered by GitBook
On this page
  • Abstract
  • Motivation
  • Specification
  • Certificate Creation Request
  • Certificate Creation Response
  • Certificate Creation Error
  • Certificate Proof Request
  • Certificate Proof Response
  • Certificate Proof Error
  • Wallet-to-Certifier Interface
  • Implementations

Was this helpful?

Edit on GitHub
Export as PDF
  1. Wallet

Certificate Creation and Revelation

PreviousSubmitting Received Payments to a WalletNextUnified Abstract Wallet-to-Application Messaging Layer

Last updated 1 year ago

Was this helpful?

Ty Everett (ty@projectbabbage.com)

Abstract

We define methods for an application to request that a wallet create and prove identity certificates. We define a set of additional messages that extend the application-to-wallet messaging layer with this functionality. We specify the functionality to be performed by the wallet as part of these processes, including a standard methodology for wallets to contact identity certificate certifiers over HTTP and carry out the signing of these documents. To keep users in control over how their data is processed and used, we allow for the wallet to obtain user consent prior to carrying out these operations.

Motivation

The identity certificate standard provides a decentralized, privacy-centric solution to digital identity, allowing users to selectively reveal their identity data. However, without a standard method for applications to create and prove these certificates, wallet support will be limited. BRC-53 provides a set of standardized methods for applications to request and interact with certificates, enabling wider adoption and integration of certificates within the ecosystem.

Specification

We define two new sets of messages to be sent over the abstract messaging layer:

Certificate Creation Request

An application may request a wallet to create a certificate by providing the following parameters:

Field
Description

certificateType

The type of certificate to create.

fieldObject

An object containing the fields to be added to the certificate.

certifierUrl

The URL of the certifier responsible for signing the certificate.

certifierPublicKey

The public identity key of the certifier responsible for signing the certificate.

The wallet will then carry out the following steps:

  1. Initialize a BRC-53 client with the primary identity key of the wallet.

  2. Generate a client nonce.

  3. Request the validationKey and serialNumber from the certifier by making a BRC-53-enabled HTTPS POST request to the certifierUrl's /initialRequest endpoint with the client nonce.

  4. Validate the received serialNumber and validationKey using the client and server nonces.

  5. Create a Certificate Signing Request (CSR) containing the certificate type, nonces, validation key, serial number, fields, and keyring.

  6. Send the CSR to the certifier's /signCertificate endpoint via an HTTP POST request.

  7. Receive and verify the signed certificate's authenticity.

  8. Store the signed certificate in the wallet's data store (how the wallet stores its data is beyond the scope of this specification).

Certificate Creation Response

Certificate Creation Error

If the Bitcoin wallet is unable to fulfill the Certificate Creation Request for any reason, we specify that it should respond with a JSON-formatted Certificate Creation Error. The fields for the object are specified as follows:

Field
Description

status

This should always be a string comprising "error".

code

A machine-readable error code. Extensions to this standard can define specific error codes and standardize additional fields. Codes are strings, for example "ERR_CERTIFIER_REJECTED_CSR".

description

All errors must have a human-readable description field that describes the error. This allows the application to represent the error for the user.

One example of a Certificate Creation Error is given below:

{
  "status": "error",
  "code": "ERR_CERTIFIER_REJECTED_CSR",
  "description": "The certifier has rejected the CSR and refused to sign the certificate."
}

Certificate Proof Request

Field
Description

certificate

fieldsToReveal

An array containing the names of the fields to be revealed to the verifier.

verifierPublicIdentityKey

The public identity key of the verifier.

The wallet will then carry out the following steps:

  1. Verify the authenticity of the provided certificate.

  2. Ensure that the application and the verifier have been granted access to the requested certificate fields (optional permissions checks).

  3. Decrypt the encrypted field revelation keys using the wallet's primary identity key.

  4. Encrypt the decrypted field revelation keys for the verifier using the verifierPublicIdentityKey.

  5. Attach the field revelation keyring to the certificate.

  6. Return the certificate with the attached field revelation keyring for presentation to the verifier for field examination.

Certificate Proof Response

Certificate Proof Error

If the Bitcoin wallet is unable to fulfill the Certificate Proof Request for any reason, we specify that it should respond with a JSON-formatted Certificate Proof Error. The fields for the object are specified as follows:

Field
Description

status

This should always be a string comprising "error".

code

A machine-readable error code. Extensions to this standard can define specific error codes and standardize additional fields. Codes are strings, for example "ERR_PERMISSION_DENIED".

description

All errors must have a human-readable description field that describes the error. This allows the application to represent the error for the user.

One example of a Certificate Proof Error is given below:

{
  "status": "error",
  "code": "ERR_PERMISSION_DENIED",
  "description": "The user denied the request to reveal these fields to this verifier at this time."
}

Wallet-to-Certifier Interface

Initial Request

The wallet initiates the communication with the certifier by sending an initial request. The initial request includes a client nonce, generated randomly by the wallet. The request is sent to the /initialRequest endpoint using the HTTP POST method.

Request fields

  • clientNonce: A randomly generated 32-byte string in base64 format.

The certifier processes the initial request and generates two nonces: serialNonce and validationNonce. The certifier calculates the serialNumber and validationKey by hashing the concatenation of clientNonce with the respective nonces. The certifier then returns these values in the response.

Response fields

  • validationKey: A base64 encoded string calculated by hashing the concatenation of clientNonce and validationNonce using SHA256.

  • serialNumber: A base64 encoded string calculated by hashing the concatenation of clientNonce and serialNonce using SHA256.

  • validationNonce: A base64 encoded nonce generated by the certifier.

  • serialNonce: A base64 encoded nonce generated by the certifier.

Certificate Signing Request

After receiving and validating the values from the initial request, the wallet creates a Certificate Signing Request (CSR) and sends it to the /signCertificate endpoint using the HTTP POST method.

Request fields

  • messageType: The string "certificateSigningRequest".

  • type: The type of certificate to create.

  • clientNonce: The client nonce generated by the wallet during the initial request.

  • serverSerialNonce: The serial nonce received from the certifier in the initial request.

  • serverValidationNonce: The validation nonce received from the certifier in the initial request.

  • validationKey: The validation key received from the certifier in the initial request.

  • serialNumber: The serial number received from the certifier in the initial request.

  • fields: An object containing encrypted fields of the certificate.

  • keyring: An object containing encrypted field revelation keys, revealed from the subject to the certifier.

The certifier processes the CSR and signs the certificate using its private signing key. The signed certificate is then returned to the wallet in the response.

Response fields

  • status: The status of the signing process, either "success" or "error".

  • description: A description of the error, if applicable.

  • code: An error code, if applicable.

Implementations

Encrypt the fields of the fieldObject using encryption and store the concealed fields and encrypted field revelation keys in the fields and keyring objects, respectively.

The response sent back over the abstract messaging layer from the wallet to the application will constitute a valid, fully-signed identity certificate with no keyring.

An application may request a wallet to prove a certificate by providing the following parameters:

The certificate to be proven.

Add the encrypted field revelation keys to the certificate field revelation keyring (as defined in ) object.

The response sent back over the abstract messaging layer from the wallet to the application will constitute a valid, fully-signed identity certificate with the attached field revelation keyring for the verifier.

The wallet and certifier communicate in a standard way over a protected HTTPS interface to facilitate the requesting and signing of a certificate. Here, we specify the requirements and fields for these communications.

We require that the wallet engages in the authentication process with the certifier, and we further require that the wallet authenticate using the same key which is the subject of the certificate issuance process. This provides a way for the certifier to know that the person making the request is the person who will be receiving the identity certificate.

certificate: The signed certificate, if the signing process is successful.

These processes have been implemented into the createCertificate and proveCertificate functions of the . The Computing with Integrity kernel (currently proprietary) implements the wallet-to-certifier communications protocol, and implements the certifier side of the protocol.

BRC-52
BRC-1
BRC-52
BRC-52
BRC-52
BRC-1
BRC-52
BRC-2
BRC-52
BRC-52
BRC-52
BRC-52
BRC-31
BRC-31
BRC-52
Babbage SDK
CoolCert
BRC-52