WebAuthn engineering reference#

This is a developer-portal reference. It assumes you are integrating WebAuthn into a relying-party backend or a JavaScript client; it does not assume you have read the W3C spec end-to-end. Every section links into the AmbiSecure tools that let you walk the binary structures while you read.

If you only have ten minutes, read Registration and Authentication — everything else is depth.

Prerequisites#

• HTTPS origin — localhost is the only HTTP exception (development).
• RP ID — pick the broadest registrable domain you want credentials to roam across.
• CSPRNG — for challenge generation.
• Persistence — for credentialId, credentialPublicKey, signCount, BE/BS, AAGUID.

Your first ceremony#

The two ceremonies are nearly symmetric. navigator.credentials.create() creates a fresh credential; .get() uses an existing one. Both produce a PublicKeyCredential object with attached binary fields.

// Registration — issued by the RP, called by the client
const credential = await navigator.credentials.create({
  publicKey: {
    challenge: challengeFromServer,        // Uint8Array, 32 bytes
    rp: { name: "Example Corp", id: "example.com" },
    user: {
      id: userIdBytes,                  // opaque, max 64 bytes
      name: "alice@example.com",
      displayName: "Alice"
    },
    pubKeyCredParams: [
      { type: "public-key", alg: -7 },     // ES256
      { type: "public-key", alg: -257 }    // RS256
    ],
    authenticatorSelection: {
      authenticatorAttachment: "cross-platform",
      requireResidentKey: true,
      userVerification: "required"
    },
    attestation: "direct"
  }
});

Registration ceremony#

The relying party server has six things to verify on registration. Skip any of these and you've broken the security model.

Authentication ceremony#

Authentication is the easier half — fewer fields to verify, no attestation, no attestedCredentialData. The signature is the load-bearing primitive.

const assertion = await navigator.credentials.get({
  publicKey: {
    challenge: challengeFromServer,        // fresh per-session
    rpId: "example.com",
    allowCredentials: [
      { type: "public-key", id: credentialIdBytes }
    ],
    userVerification: "required"
  }
});

Server verification:

1. Decode clientDataJSON; verify type, challenge, origin.
2. Compute SHA-256(rpId); compare with authData.rpIdHash.
3. Verify UP / UV per policy.
4. Verify the signature: verify(publicKey, authData || SHA-256(clientDataJSON), signature).
5. Verify signCount > storedSignCount (or both 0 — many platform authenticators).
6. Update stored signCount; mint session.

authenticatorData reference#

The exact byte layout of authenticatorData. Use the authData parser to walk live data.

clientDataJSON reference#

JSON object built by the user agent. The bytes are what the authenticator's signature covers (after SHA-256).

{
  "type": "webauthn.get",
  "challenge": "aabbccddeeff...",    // base64url
  "origin": "https://login.example.com",
  "crossOrigin": false
}

Attestation reference#

The attestationObject is a CBOR map keyed by short strings. See technologies / attestation for the full deep dive on each fmt.

Flags — BE / BS / UP / UV#

Error handling#

Common DOMExceptions during a ceremony:

• NotAllowedError — user cancelled or timed out, or browser refused due to RP ID / origin mismatch.
• InvalidStateError — credential already registered (de-dup mismatch on registration).
• NotSupportedError — none of the requested algorithms are supported by the available authenticator.
• SecurityError — RP ID is not a registrable suffix of the origin.
• ConstraintError — userVerification: "required" but the authenticator can't perform UV.

Found a bug or have a suggestion? File at /contact/. This portal is static and version-pinned; planned migration target is docs.ambimat.com for a future Phase.