BSV blockchainBSV blockchain

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:

BRC-103Mutual authentication

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.

FieldDescription
versionProtocol version string
messageTypeinitialRequest
identityKeyIdentity key of the sender
initialNonceA 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
requestedCertificatesThe 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.

FieldDescription
versionProtocol version string
messageTypeinitialResponse
identityKeyIdentity key of the receiver
initialNonceThe nonce the receiver created
yourNonceThe initialNonce of the request, echoed
signatureDER signature of the receiver over the two nonces, as an array of byte values
requestedCertificatesThe certificates the receiver asks for, or an empty set
certificatesOptional. 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

FieldDescription
versionProtocol version string
messageTypegeneral
identityKeyIdentity key of the sender
nonceA fresh random value from the sender, base64
yourNonceThe nonce the sender last received from the other peer, base64
payloadThe signed application data, as an array of byte values
signatureDER signature of the sender, as an array of byte values

Request headers and signature

Each HTTP request after the handshake carries these headers:

HeaderDescription
x-bsv-auth-versionProtocol version
x-bsv-auth-identity-keyIdentity key of the client
x-bsv-auth-nonceA fresh nonce from the client, base64
x-bsv-auth-your-nonceThe last nonce of the server, base64
x-bsv-auth-request-idA random 32 byte value, base64
x-bsv-auth-signatureECDSA signature, hexadecimal DER

The signature covers, in this order:

  1. The request ID, 32 bytes.
  2. The method, the path and the query string, each with its length. An empty query string is written as length -1.
  3. 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 except x-bsv-auth-*, content-type without its parameters, and authorization.
  4. The length of the body, -1 when 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:

StatusCodeCause
401UNAUTHORIZED or ERR_AUTH_FAILEDThe request has no authentication headers, or they are not valid
408CERTIFICATE_TIMEOUTThe server waited 30 seconds for certificates and none arrived
500ERR_RESPONSE_SIGNING_FAILED or ERR_INTERNAL_SERVER_ERRORThe 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.
  • requestedCertificates is 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-* or authorization header. 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.

To learn more about mutual authentication on the BSV blockchain, review these articles: