How passwordless-lib/fido2-net-lib works
Purpose and deliverables
A .NET 8+ FIDO2/WebAuthn relying-party library for issuing registration/assertion challenges and cryptographically validating returned credentials. The repository produces reusable core, model, ASP.NET Core integration, Blazor WASM interop, CTAP2, and development-support packages. Solution entry point: fido2-net-lib.sln.
Core relying-party engine
Src/Fido2/Fido2.cs implements IFido2 (Src/Fido2/IFido2.cs): it creates credential-registration and assertion options, then verifies attestation and assertion responses. This is the security boundary between untrusted browser/authenticator payloads and application-owned credential storage. Its parameter wrappers and response types drive the primary public API.
Protocol models and serialization
Src/Fido2.Models/Fido2Configuration.cs, Src/Fido2.Models/CredentialCreateOptions.cs, and Src/Fido2.Models/AssertionOptions.cs define configuration and browser-facing WebAuthn option payloads. Raw browser response models, credential descriptors, extension inputs/outputs, metadata schemas, and source-generated JSON context are centralized in Src/Fido2.Models, keeping wire contracts separate from verification logic.
Registration and authentication verification
Registration accepts an attestation response plus originally issued options, validates client/origin/challenge/authenticator data, dispatches its attestation format verifier, and returns a public key and credential data for caller persistence. Key paths: Src/Fido2/AuthenticatorAttestationResponse.cs, Src/Fido2/AttestationFormat/AttestationVerifier.cs, Src/Fido2/AttestationFormat/Packed.cs.
Authentication accepts assertion data, stored public key and signature counter, verifies ownership through application callbacks, validates the signature, and returns an updated counter: Src/Fido2/AuthenticatorAssertionResponse.cs, Src/Fido2/MakeAssertionParams.cs.
Trust, metadata, and cryptography
Attestation trust decisions are separated behind metadata interfaces and repositories. Src/Fido2/IMetadataService.cs and Src/Fido2/Metadata/Fido2MetadataServiceRepository.cs support FIDO Metadata Service retrieval/validation; Src/Fido2.AspNet/DistributedCacheMetadataService.cs adds cache-backed use in ASP.NET Core. Format-specific validation covers TPM, Android, Apple, U2F, packed, and none under Src/Fido2/AttestationFormat. Cryptographic, ASN.1, CBOR, certificate, and authenticator-data parsing live in Src/Fido2/Extensions/CryptoUtils.cs, Src/Fido2/Asn1Element.cs, and Src/Fido2/Cbor.
Host integration and browser boundary
ASP.NET Core applications register the engine through DI extensions in Src/Fido2.AspNet/Fido2NetLibBuilderExtensions.cs; hosts own sessions/challenge lifecycle and durable user/credential storage. Browser WebAuthn ceremony calls remain client-side: Src/Fido2.BlazorWebAssembly/WebAuthn.cs bridges to Src/Fido2.BlazorWebAssembly/wwwroot/js/WebAuthn.ts. Thus the browser talks to platform/roaming authenticators, while the server remains the verifier and credential record authority.
Executable examples and infrastructure
Demo/Program.cs starts the ASP.NET Core reference app; Demo/DemoController.cs exposes registration/authentication ceremony endpoints, paired with browser scripts in Demo/wwwroot/js. BlazorWasmDemo/Server/Program.cs hosts the WASM example, whose client bootstraps at BlazorWasmDemo/Client/Program.cs. Development-only in-memory credential/metadata support is in Src/Fido2.Development/DevelopmentInMemoryStore.cs. CI runs through .github/workflows/main.yml; Azure deployment and container hosting are represented by .github/workflows/azure-deploy.yml and BlazorWasmDemo/Server/Dockerfile.
Main entry points: Fido2.cs Fido2 engine · AuthenticatorAttestationResponse.cs Registration verification · AttestationVerifier.cs Attestation dispatcher · DemoController.cs Demo ceremonies
Components 21
Relying-party core
Reusable verification engine and WebAuthn contracts.
- IFido2 API · Public ceremony creation and verification contract.
Src/Fido2/IFido2.cs - Fido2 engine · Security boundary for untrusted WebAuthn payloads.
Src/Fido2/Fido2.cs - Options & configuration · Browser-facing WebAuthn option payloads and relying-party configuration.
Src/Fido2.Models/Fido2Configuration.cs - Registration verification · Validates registration responses and yields credential material.
Src/Fido2/AuthenticatorAttestationResponse.cs - Assertion verification · Validates assertions and returns an updated signature counter.
Src/Fido2/AuthenticatorAssertionResponse.cs
Trust and parsing
Attestation trust, format validation, and binary security primitives.
- Attestation dispatcher
Src/Fido2/AttestationFormat/AttestationVerifier.cs - Packed attestation · One format-specific attestation validator.
Src/Fido2/AttestationFormat/Packed.cs - Metadata service · Abstraction for attestation trust decisions.
Src/Fido2/IMetadataService.cs - Metadata repository · Retrieves and validates FIDO metadata.
Src/Fido2/Metadata/Fido2MetadataServiceRepository.cs - Crypto & binary parsing · Cryptography, ASN.1, CBOR, certificates, and authenticator-data parsing.
Src/Fido2/Extensions/CryptoUtils.cs
Host integrations and examples
Server registration, ceremony endpoints, and browser clients.
- ASP.NET Core DI · Registers the relying-party engine with application DI.
Src/Fido2.AspNet/Fido2NetLibBuilderExtensions.cs - Distributed metadata cache · Cache-backed metadata support for ASP.NET Core hosts.
Src/Fido2.AspNet/DistributedCacheMetadataService.cs - Reference demo API · Exposes registration and authentication ceremony endpoints.
Demo/Program.cs - Demo ceremonies
Demo/DemoController.cs - Blazor WebAuthn bridge · Calls browser WebAuthn APIs from Blazor.
Src/Fido2.BlazorWebAssembly/WebAuthn.cs - Browser WebAuthn · Invokes platform or roaming authenticators.
Src/Fido2.BlazorWebAssembly/wwwroot/js/WebAuthn.ts - Blazor WASM host · Hosts the WebAssembly example.
BlazorWasmDemo/Server/Program.cs - Blazor WASM client
BlazorWasmDemo/Client/Program.cs - Development in-memory store · In-memory credential and metadata support.
Src/Fido2.Development/DevelopmentInMemoryStore.cs
Delivery
- CI workflow
.github/workflows/main.yml - WASM server container
BlazorWasmDemo/Server/Dockerfile
Connections 22
- IFido2 API → Fido2 engine: implemented by
- Fido2 engine → Options & configuration: issues options
- Fido2 engine → Registration verification: verifies registration
- Fido2 engine → Assertion verification: verifies assertion
- Registration verification → Attestation dispatcher: dispatches format
- Registration verification → Crypto & binary parsing: validates signed data
- Assertion verification → Crypto & binary parsing: verifies signature
- Attestation dispatcher → Packed attestation: supports
- Attestation dispatcher → Metadata service: evaluates trust through
- Metadata repository → Metadata service: implements
- ASP.NET Core DI → Fido2 engine: registers
- Distributed metadata cache → Metadata service: implements
- Reference demo API → ASP.NET Core DI: uses
- Reference demo API → Demo ceremonies: hosts
- Demo ceremonies → Fido2 engine: runs ceremonies
- Demo ceremonies → Development in-memory store: uses in development
- Blazor WebAuthn bridge → Browser WebAuthn: invokes
- Blazor WASM client → Blazor WebAuthn bridge: uses
- Blazor WASM host → Blazor WASM client: hosts
- Blazor WASM host → ASP.NET Core DI: registers verifier
- CI workflow → Fido2 engine: builds and validates
- WASM server container → Blazor WASM host: packages