-
Notifications
You must be signed in to change notification settings - Fork 0
Data Flow Architecture
- Introduction
- System Architecture Overview
- Core Data Transformation Components
- CBOR Encoding Infrastructure
- COSE Key Management
- WebAuthn Data Structures
- Post-Quantum Cryptographic Components
- Authentication Ceremony Data Flow
- Data Integrity and Security Mechanisms
- Canonical CBOR Requirements
- Performance Considerations
- Troubleshooting Guide
- Conclusion
The Post-Quantum WebAuthn Platform implements a comprehensive authentication system that seamlessly integrates classical and post-quantum cryptographic algorithms. This architecture provides robust security through CBOR encoding, COSE key management, and WebAuthn data structures, specifically designed to withstand quantum computing threats while maintaining backward compatibility with existing WebAuthn standards.
The platform's data flow architecture ensures secure transmission and processing of authentication data through multiple layers of encoding, validation, and cryptographic protection. This document details the complete data pathway from client challenge generation to credential verification, emphasizing the structured transformations that occur throughout the system.
The Post-Quantum WebAuthn Platform follows a layered architecture that separates concerns between client-side processing, server-side validation, and cryptographic operations. The system is built around three primary data transformation layers: CBOR encoding for binary serialization, COSE key management for cryptographic operations, and WebAuthn data structures for authentication protocol compliance.
graph TB
subgraph "Client Layer"
Client[Web Client]
Challenge[Challenge Generation]
CBOR_Encode[CBOR Encoding]
end
subgraph "Network Layer"
Network[HTTP Transport]
Validation[Protocol Validation]
end
subgraph "Server Layer"
Server[Fido2Server]
WebAuthn_Parse[WebAuthn Parsing]
COSE_Verify[COSE Verification]
end
subgraph "Cryptographic Layer"
PQ_Algorithms[Post-Quantum Algorithms]
Classical_Algorithms[Classical Algorithms]
OQS_Lib[liboqs Integration]
end
subgraph "Storage Layer"
Storage[Key Storage]
Metadata[Authenticator Metadata]
end
Client --> Challenge
Challenge --> CBOR_Encode
CBOR_Encode --> Network
Network --> Validation
Validation --> Server
Server --> WebAuthn_Parse
WebAuthn_Parse --> COSE_Verify
COSE_Verify --> PQ_Algorithms
COSE_Verify --> Classical_Algorithms
PQ_Algorithms --> OQS_Lib
Classical_Algorithms --> OQS_Lib
OQS_Lib --> Storage
Server --> Metadata
Diagram sources
- fido2/server.py
- server/server/routes/simple.py
- fido2/cbor.py
The platform's data flow architecture consists of three interconnected components that handle different aspects of authentication data processing:
The CBOR layer provides binary serialization capabilities essential for efficient data transmission and storage. It handles the conversion between Python objects and binary formats required by WebAuthn protocols.
The COSE layer manages cryptographic key formats and signature operations, supporting both classical and post-quantum cryptographic algorithms through standardized key representations.
The WebAuthn layer defines the high-level data structures used throughout the authentication process, including authenticator data, attestation objects, and client data collections.
classDiagram
class CBORProcessor {
+encode(data) bytes
+decode(data) Any
+dump_int(value, mt) bytes
+dump_dict(data) bytes
+load_int(ai, data) Tuple
+load_map(ai, data) Tuple
}
class COSEProcessor {
+CoseKey
+MLDSA44
+MLDSA65
+MLDSA87
+verify(message, signature) void
+from_cryptography_key(key) CoseKey
}
class WebAuthnProcessor {
+AuthenticatorData
+AttestationObject
+CollectedClientData
+PublicKeyCredentialCreationOptions
+create(rp_id_hash, flags, counter) AuthenticatorData
+parse(auth_data) AttestedCredentialData
}
CBORProcessor --> COSEProcessor : "serializes/deserializes"
COSEProcessor --> WebAuthnProcessor : "validates signatures"
WebAuthnProcessor --> CBORProcessor : "encodes/decodes"
Diagram sources
- fido2/cbor.py
- fido2/cose.py
- fido2/webauthn.py
Section sources
- fido2/cbor.py
- fido2/cose.py
- fido2/webauthn.py
The CBOR encoding infrastructure provides a minimal but comprehensive implementation of the Concise Binary Object Representation format, specifically tailored for FIDO 2 CTAP requirements. This implementation supports essential data types including integers, booleans, strings, byte strings, arrays, and maps with strict canonical ordering requirements.
The CBOR processor implements several fundamental functions for data serialization and deserialization:
- Integer Serialization: Handles positive and negative integers with automatic size optimization
- Dictionary Processing: Enforces canonical key ordering for deterministic encoding
- Array Operations: Processes sequences with proper length encoding
- Validation Logic: Ensures data integrity through strict parsing rules
The implementation enforces strict canonical CBOR requirements as defined in the FIDO 2 specifications:
flowchart TD
Start([CBOR Processing Start]) --> ValidateInput["Validate Input Parameters"]
ValidateInput --> CheckType{"Check Data Type"}
CheckType --> |Integer| SerializeInt["Serialize Integer<br/>Optimize Size"]
CheckType --> |Boolean| SerializeBool["Serialize Boolean"]
CheckType --> |String| SerializeText["Serialize Text<br/>UTF-8 Encoding"]
CheckType --> |Bytes| SerializeBytes["Serialize Bytes<br/>Length Prefix"]
CheckType --> |Array| SerializeList["Serialize Array<br/>Canonical Order"]
CheckType --> |Map| SerializeDict["Serialize Dictionary<br/>Key Sorting"]
SerializeInt --> ValidateCanonical["Validate Canonical Form"]
SerializeBool --> ValidateCanonical
SerializeText --> ValidateCanonical
SerializeBytes --> ValidateCanonical
SerializeList --> ValidateCanonical
SerializeDict --> ValidateCanonical
ValidateCanonical --> Success["CBOR Output"]
Success --> End([Processing Complete])
Diagram sources
- fido2/cbor.py
Section sources
- fido2/cbor.py
- tests/test_cbor.py
The COSE key management system provides comprehensive support for cryptographic key operations, including post-quantum ML-DSA algorithms and classical cryptographic primitives. The system implements a flexible key format that accommodates various algorithm types while maintaining interoperability with WebAuthn standards.
The platform supports three ML-DSA parameter sets, each optimized for different security levels and performance characteristics:
| Parameter Set | Public Key Length | Signature Length | Algorithm Identifier |
|---|---|---|---|
| ML-DSA-44 | 1312 bytes | 2420 bytes | -48 |
| ML-DSA-65 | 1952 bytes | 3309 bytes | -49 |
| ML-DSA-87 | 2592 bytes | 4627 bytes | -50 |
Each supported algorithm is represented by a dedicated COSE key class that inherits from the base CoseKey class:
classDiagram
class CoseKey {
<<abstract>>
+ALGORITHM : int
+verify(message, signature) void
+from_cryptography_key(key) CoseKey
+set_assertion_debug_data(auth_data, client_data) void
+_log_signature_debug(algorithm, message, signature, public_key) void
}
class MLDSA44 {
+ALGORITHM : -48
+_HASH_ALG : SHA256
+verify(message, signature) void
+from_cryptography_key(key) MLDSA44
}
class MLDSA65 {
+ALGORITHM : -49
+_HASH_ALG : SHA256
+verify(message, signature) void
+from_cryptography_key(key) MLDSA65
}
class MLDSA87 {
+ALGORITHM : -50
+_HASH_ALG : SHA256
+verify(message, signature) void
+from_cryptography_key(key) MLDSA87
}
class ES256 {
+ALGORITHM : -7
+verify(message, signature) void
+from_cryptography_key(key) ES256
}
CoseKey <|-- MLDSA44
CoseKey <|-- MLDSA65
CoseKey <|-- MLDSA87
CoseKey <|-- ES256
Diagram sources
- fido2/cose.py
Section sources
- fido2/cose.py
- prebuilt_liboqs/linux-x86_64/include/oqs/sig_ml_dsa.h
The WebAuthn data structures provide the foundation for authentication operations, defining the binary formats for authenticator data, attestation objects, and client data collections. These structures ensure protocol compliance while supporting the diverse cryptographic requirements of modern authentication systems.
Authenticator data serves as the core container for authentication state information, including cryptographic material, authentication counters, and attestation data:
classDiagram
class AuthenticatorData {
+bytes rp_id_hash
+FLAG flags
+int counter
+Optional~AttestedCredentialData~ credential_data
+Optional~Mapping~ extensions
+create(rp_id_hash, flags, counter, credential_data, extensions) AuthenticatorData
+is_user_present() bool
+is_user_verified() bool
+is_attested() bool
+has_extension_data() bool
}
class AttestedCredentialData {
+Aaguid aaguid
+bytes credential_id
+CoseKey public_key
+create(aaguid, credential_id, public_key) AttestedCredentialData
+unpack_from(data) Tuple
+from_ctap1(key_handle, public_key) AttestedCredentialData
}
class AttestationObject {
+str fmt
+AuthenticatorData auth_data
+Mapping~str, Any~ att_stmt
+create(fmt, auth_data, att_stmt) AttestationObject
+from_ctap1(app_param, registration) AttestationObject
}
class CollectedClientData {
+str type
+bytes challenge
+str origin
+bool cross_origin
+create(type, challenge, origin, cross_origin) CollectedClientData
+b64 : str
+hash : bytes
}
AuthenticatorData --> AttestedCredentialData : "contains"
AttestationObject --> AuthenticatorData : "wraps"
AttestationObject --> CollectedClientData : "references"
Diagram sources
- fido2/webauthn.py
The platform defines precise binary formats for each data structure to ensure consistent serialization and deserialization across different implementations:
| Structure | Binary Layout | Key Components |
|---|---|---|
| AuthenticatorData | RP ID Hash (32) | Flags (1) | Counter (4) | Credential Data | Extensions | RP hash, authentication flags, signature counter |
| AttestedCredentialData | AAGUID (16) | Credential ID Length (2) | Credential ID | COSE Key | Authenticator ID, credential identifier, public key |
| AttestationObject | CBOR Encoded Object | Format type, authenticator data, attestation statement |
Section sources
- fido2/webauthn.py
The platform's post-quantum cryptographic infrastructure centers around ML-DSA (Module-Lattice-based Digital Signature Algorithm) implementations, providing resistance against quantum computing attacks while maintaining compatibility with existing WebAuthn frameworks.
Each ML-DSA variant implements the same interface but with different security parameters:
sequenceDiagram
participant Client as "Client Device"
participant Server as "Authentication Server"
participant OQS as "liboqs Library"
participant Crypto as "Cryptographic Backend"
Client->>Server : Registration Request
Server->>OQS : Generate ML-DSA Key Pair
OQS->>Crypto : Generate Key Material
Crypto-->>OQS : Public Key (1312/1952/2592 bytes)
OQS-->>Server : ML-DSA Public Key
Server->>Server : Create Attestation Object
Server-->>Client : Registration Response
Client->>Server : Authentication Request
Server->>Server : Retrieve Stored Key
Server->>Client : Challenge + Credential List
Client->>OQS : Sign Challenge
OQS->>Crypto : Generate Signature
Crypto-->>OQS : Signature (2420/3309/4627 bytes)
OQS-->>Client : Signed Challenge
Client-->>Server : Assertion Response
Server->>OQS : Verify Signature
OQS->>Crypto : Validate Signature
Crypto-->>OQS : Verification Result
OQS-->>Server : Verification Status
Server-->>Client : Authentication Result
Diagram sources
- fido2/cose.py
- server/server/pqc.py
The platform includes sophisticated algorithm detection mechanisms to ensure compatibility across different deployment environments:
flowchart TD
Start([Algorithm Detection]) --> LoadOQS["Load liboqs Module"]
LoadOQS --> CheckAvailable{"liboqs Available?"}
CheckAvailable --> |No| Error["Raise ImportError"]
CheckAvailable --> |Yes| GetEnabled["Query Enabled Algorithms"]
GetEnabled --> FilterSupported["Filter Supported ML-DSA Variants"]
FilterSupported --> ValidateKeys["Validate Key Parameters"]
ValidateKeys --> Ready["Algorithms Ready"]
Error --> End([Detection Complete])
Ready --> End
Diagram sources
- server/server/pqc.py
Section sources
- fido2/cose.py
- server/server/pqc.py
- prebuilt_liboqs/linux-x86_64/include/oqs/sig_ml_dsa.h
The authentication ceremony represents the core interaction between clients and servers during WebAuthn operations. This process involves multiple data transformations and validations that ensure security and integrity throughout the authentication lifecycle.
The registration ceremony establishes new credentials with the authentication server:
sequenceDiagram
participant Browser as "Browser/Web Client"
participant Authenticator as "Authenticator Device"
participant Server as "Authentication Server"
participant Storage as "Credential Storage"
Browser->>Server : GET /register/options
Server->>Server : Generate Challenge
Server->>Server : Create Options
Server-->>Browser : Registration Options
Browser->>Authenticator : Create Credential
Authenticator->>Authenticator : Generate Key Pair
Authenticator->>Authenticator : Create Attestation
Authenticator-->>Browser : Registration Response
Browser->>Server : POST /register/finish
Server->>Server : Parse Registration Data
Server->>Server : Verify Attestation
Server->>Server : Store Credential
Server-->>Browser : Registration Success
Note over Server,Storage : Credential stored with metadata
Diagram sources
- server/server/routes/simple.py
- tests/test_mldsa_registration_authentication.py
The authentication ceremony verifies existing credentials through challenge-response mechanisms:
sequenceDiagram
participant Browser as "Browser/Web Client"
participant Authenticator as "Authenticator Device"
participant Server as "Authentication Server"
participant Crypto as "Cryptographic Engine"
Browser->>Server : GET /authenticate/options
Server->>Server : Select Credentials
Server->>Server : Generate Challenge
Server-->>Browser : Authentication Options
Browser->>Authenticator : Authenticate
Authenticator->>Authenticator : Sign Challenge
Authenticator-->>Browser : Assertion Response
Browser->>Server : POST /authenticate/finish
Server->>Server : Parse Assertion Data
Server->>Crypto : Verify Signature
Crypto->>Crypto : Validate Authenticator Data
Crypto-->>Server : Verification Result
Server->>Server : Update Counter
Server-->>Browser : Authentication Success
Diagram sources
- server/server/routes/simple.py
- tests/test_mldsa_registration_authentication.py
Section sources
- server/server/routes/simple.py
- tests/test_mldsa_registration_authentication.py
The platform implements multiple layers of security and integrity protection to ensure the authenticity and reliability of authentication data throughout the entire processing pipeline.
Anti-replay protection is implemented through multiple mechanisms:
- Challenge Validation: Each authentication operation uses a unique, cryptographically random challenge
- Counter Increment: Signature counters prevent replay of previously used credentials
- Timestamp Validation: Time-based checks ensure freshness of authentication requests
Cryptographic binding ensures that authentication data cannot be tampered with or reused:
flowchart TD
Challenge[Random Challenge] --> Hash[SHA-256 Hash]
Hash --> ClientData[Client Data JSON]
ClientData --> CBOR_Encode[CBOR Encoding]
CBOR_Encode --> AuthenticatorData[Authenticator Data]
AuthenticatorData --> Signature[Digital Signature]
Signature --> Verification[Signature Verification]
Verification --> Integrity{Integrity Check}
Integrity --> |Pass| Success[Authentication Success]
Integrity --> |Fail| Failure[Authentication Failure]
subgraph "Security Layers"
Challenge
Hash
ClientData
CBOR_Encode
AuthenticatorData
Signature
Verification
end
Diagram sources
- fido2/webauthn.py
The platform implements comprehensive data validation at multiple stages:
| Validation Stage | Checks Performed | Security Benefit |
|---|---|---|
| CBOR Decoding | Canonical form, length limits | Prevent malformed data injection |
| COSE Key Parsing | Algorithm compatibility, parameter validation | Ensure cryptographic integrity |
| WebAuthn Structure | Field presence, type checking | Maintain protocol compliance |
| Cryptographic Verification | Signature validity, key matching | Confirm authenticity and ownership |
Section sources
- fido2/cbor.py
- fido2/webauthn.py
The platform strictly adheres to canonical CBOR requirements as specified in RFC 8949 and FIDO 2 standards. These requirements ensure deterministic encoding and prevent ambiguity in data interpretation.
The CBOR implementation enforces the following canonical encoding rules:
- Integer Encoding: Smallest possible representation using major type 0 or 1
- String Encoding: UTF-8 encoding with shortest possible representation
- Array Ordering: Elements encoded in increasing key order for maps
- Byte String Length: Minimal length encoding for all data types
The validation process ensures compliance with canonical CBOR requirements:
flowchart TD
Input[CBOR Input] --> Parse[Parse Header]
Parse --> ValidateType{Validate Type}
ValidateType --> |Invalid| Error[Validation Error]
ValidateType --> |Valid| ValidateLength{Validate Length}
ValidateLength --> |Invalid| Error
ValidateLength --> |Valid| ValidateContent{Validate Content}
ValidateContent --> |Invalid| Error
ValidateContent --> |Valid| Canonical{Check Canonical}
Canonical --> |Not Canonical| Error
Canonical --> |Canonical| Success[Validation Success]
Error --> Reject[Reject Data]
Success --> Accept[Accept Data]
Diagram sources
- fido2/cbor.py
Section sources
- fido2/cbor.py
- tests/test_cbor.py
The platform's architecture incorporates several performance optimization strategies to ensure efficient operation under various load conditions.
Efficient memory usage is achieved through:
- Streaming Processing: Large data structures processed in chunks
- Lazy Loading: Components loaded only when required
- Buffer Reuse: Memory buffers recycled for repeated operations
Cryptographic operations are optimized for performance:
- Algorithm Selection: Automatic selection of fastest available algorithms
- Batch Processing: Multiple operations combined where possible
- Hardware Acceleration: Utilization of hardware-accelerated cryptographic functions
Network performance is enhanced through:
- Compression: CBOR encoding reduces data size compared to JSON
- Connection Pooling: Persistent connections reduce handshake overhead
- Caching: Frequently accessed data cached in memory
Common issues and their solutions when working with the Post-Quantum WebAuthn Platform:
Problem: Malformed CBOR data causing parsing failures Solution: Ensure data conforms to canonical CBOR requirements and validate using the provided test vectors
Problem: Integer overflow in CBOR encoding Solution: Verify integer values fall within supported ranges and use appropriate major types
Problem: ML-DSA signatures failing verification Solution: Check that the correct ML-DSA variant is selected and verify key parameter compatibility
Problem: Cryptographic backend not available Solution: Ensure liboqs library is properly installed and accessible
Problem: Authenticator data validation failures Solution: Verify RP ID hash matches expected value and check flag consistency
Problem: Challenge replay protection triggered Solution: Ensure challenges are unique and timestamps are current
Section sources
- tests/test_cbor.py
- tests/test_cose.py
- tests/test_webauthn.py
The Post-Quantum WebAuthn Platform demonstrates a sophisticated approach to authentication architecture that successfully integrates classical and post-quantum cryptographic technologies. Through its layered design encompassing CBOR encoding, COSE key management, and WebAuthn data structures, the platform provides robust security while maintaining compatibility with existing standards.
The platform's emphasis on canonical CBOR requirements, comprehensive data validation, and anti-replay mechanisms ensures reliable operation across diverse deployment scenarios. The inclusion of ML-DSA post-quantum algorithms positions the platform to withstand future quantum computing threats while preserving backward compatibility with classical cryptographic systems.
Future enhancements could include expanded post-quantum algorithm support, additional performance optimizations, and enhanced monitoring capabilities for production deployments. The modular architecture facilitates such improvements while maintaining the system's core security guarantees.