Certificate Creation and Revelation
Last updated
Was this helpful?
Last updated
Was this helpful?
Ty Everett (ty@projectbabbage.com)
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.
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.
We define two new sets of messages to be sent over the abstract messaging layer:
An application may request a wallet to create a certificate by providing the following parameters:
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:
Initialize a BRC-53 client with the primary identity key of the wallet.
Generate a client nonce.
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.
Validate the received serialNumber
and validationKey
using the client and server nonces.
Create a Certificate Signing Request (CSR) containing the certificate type, nonces, validation key, serial number, fields, and keyring.
Send the CSR to the certifier's /signCertificate
endpoint via an HTTP POST request.
Receive and verify the signed certificate's authenticity.
Store the signed certificate in the wallet's data store (how the wallet stores its data is beyond the scope of this specification).
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:
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:
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:
Verify the authenticity of the provided certificate.
Ensure that the application and the verifier have been granted access to the requested certificate fields (optional permissions checks).
Decrypt the encrypted field revelation keys using the wallet's primary identity key.
Encrypt the decrypted field revelation keys for the verifier using the verifierPublicIdentityKey
.
Attach the field revelation keyring to the certificate.
Return the certificate with the attached field revelation keyring for presentation to the verifier for field examination.
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:
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:
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.
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.
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.