BRC-103 mutual authentication
BRC-103Peer-to-peer mutual authentication and certificate exchange is the protocol in which two peers prove to each other that they control their identity keysThe compressed public key of a wallet, 66 hexadecimal characters, that identifies it to other peers, and then sign every message they exchange. MessageBox and AuthSocket use it. Use this page to look up its messages, for example to build a client or a server in another language.
BRC-31 Authrite is a separate protocol, not another name for BRC-103.
At a glance
Select a fact to see its detail:
Every message is a JSON AuthMessage. The examples on this page use version 0.1.
Handshake messages
The handshake takes two messages, and a third exchange when a peer asks for certificates. Over HTTP, where BRC-104The standard that binds BRC-103 to HTTP binds the protocol, each message is the JSON body of a request or response at /.well-known/auth, with no authentication headers. Over Socket.IO each message is a frame on the authMessage event, as described in AuthSocket WebSocket protocol.
Initial request
The peer that starts the exchange sends an initialRequest message. It is unsigned, and it has no nonce, payload or signature member.
| Field | Description |
|---|---|
version | Protocol version string |
messageType | initialRequest |
identityKey | Identity key of the sender |
initialNonce | A random nonceA random value used once in an exchange, so that a replayed message can be told from a fresh one of the sender, base64 |
requestedCertificates | The certificates the sender asks the other peer for, or an empty set |
{
"version": "0.1",
"messageType": "initialRequest",
"identityKey": "IDENTITY_KEY",
"initialNonce": "INITIAL_NONCE",
"requestedCertificates": { "certifiers": [], "types": {} }
}Replace IDENTITY_KEY with the identity key of the sender and INITIAL_NONCE with a new random nonce, base64 encoded.
Initial response
The receiver answers with an initialResponse message. It creates its own nonce and echoes the nonce it received. The initiator verifies the signature, and then treats the receiver as authenticated.
| Field | Description |
|---|---|
version | Protocol version string |
messageType | initialResponse |
identityKey | Identity key of the receiver |
initialNonce | The nonce the receiver created |
yourNonce | The initialNonce of the request, echoed |
signature | DER signature of the receiver over the two nonces, as an array of byte values |
requestedCertificates | The certificates the receiver asks for, or an empty set |
certificates | Optional. Certificates the receiver shares right away |
Certificate exchange
A peer that sets requestedCertificates asks for BRC-52Identity certificates, whose fields are encrypted one by one so a holder can reveal only some of them certificates. The set has two members, certifiers and types. certifiers lists the public keys of the certifiers it accepts, and types maps each certificate type ID to the field names it wants. The other peer answers with a certificateResponse message that carries a list of verifiable certificates, each with the keys to read only the fields it chose to reveal.
The verifier checks the signature of the certifier before it accepts a field, and treats a certificate as revoked when its revocationOutpoint is spent.
Signed messages after the handshake
Once both peers are authenticated, each message is a general message signed by its sender. Over HTTP the signature and the nonces travel in headers. Over Socket.IO they are fields of the frame.
General message
| Field | Description |
|---|---|
version | Protocol version string |
messageType | general |
identityKey | Identity key of the sender |
nonce | A fresh random value from the sender, base64 |
yourNonce | The nonce the sender last received from the other peer, base64 |
payload | The signed application data, as an array of byte values |
signature | DER signature of the sender, as an array of byte values |
Request headers and signature
Each HTTP request after the handshake carries these headers:
| Header | Description |
|---|---|
x-bsv-auth-version | Protocol version |
x-bsv-auth-identity-key | Identity key of the client |
x-bsv-auth-nonce | A fresh nonce from the client, base64 |
x-bsv-auth-your-nonce | The last nonce of the server, base64 |
x-bsv-auth-request-id | A random 32 byte value, base64 |
x-bsv-auth-signature | ECDSA signature, hexadecimal DER |
The signature covers, in this order:
- The request ID, 32 bytes.
- The method, the path and the query string, each with its length. An empty query string is written as length
-1. - The number of headers, then each header as a length and name followed by a length and value, sorted by name. Only three kinds of header are signed: every
x-bsv-*header exceptx-bsv-auth-*,content-typewithout its parameters, andauthorization. - The length of the body,
-1when there is none, then the body.
Lengths are variable length integers.
Response headers and signature
The server answers with the same six headers. They carry its own identity key, a fresh nonce of its own, and the last nonce of the client in x-bsv-auth-your-nonce. The signature covers the request ID, the status code, the headers and the body.
The headers signed in a response are the x-bsv-* headers except x-bsv-auth-*, and authorization. Everything else, such as location, set-cookie and content-type, is not signed.
Errors and security
The Express middleware returns the errors below, and the signatures leave some request data unprotected.
HTTP error responses
The Express middleware answers a request that fails authentication with one of these:
| Status | Code | Cause |
|---|---|---|
401 | UNAUTHORIZED or ERR_AUTH_FAILED | The request has no authentication headers, or they are not valid |
408 | CERTIFICATE_TIMEOUT | The server waited 30 seconds for certificates and none arrived |
500 | ERR_RESPONSE_SIGNING_FAILED or ERR_INTERNAL_SERVER_ERROR | The server could not sign its response, or failed in another way |
With the option allowUnauthenticated: true, a request without headers goes through, and the identity key the application sees is unknown.
What the signature does not cover
- A nonce is not a single use token on its own. Keep the session state the SDK relies on, and make the protected operations of your application idempotent.
- The signature of the initial response covers the two nonces and nothing else. The certificate request and any certificates in that response can be changed in transit. Disclose no plaintext and authorize no side effect from a certificate request callback.
requestedCertificatesis an allowlist, not a statement that every listed type or field was supplied. Grant access only on the certificates you received and validated after the handshake.- The request signature does not cover the scheme and host, cookies, forwarding headers or other standard headers. Fix the expected host at a trusted edge, never pick a tenant from metadata the signature omits, and put every value that decides authorization in a signed
x-bsv-*orauthorizationheader. Use separate server identity keys for hosts that are separate principals. - BRC-103 signs messages and does not encrypt them. Add transport encryption such as TLS to hide message contents, lengths and frequency on the network.
Related articles
To learn more about mutual authentication on the BSV blockchain, review these articles: