Glossary & References

Glossary & References

Table of Contents

1. Introduction
2. Core Acronyms and Definitions
3. FIDO2/WebAuthn Specifications
4. CTAP2 Protocol Components
5. COSE and CBOR Standards
6. Post-Quantum Cryptography
7. HID Transport Layer
8. Metadata Service (MDS)
9. Platform Implementation Details
10. Additional Reading Materials

Introduction

The Post-Quantum WebAuthn Platform implements the FIDO2/WebAuthn standard with integrated post-quantum cryptographic algorithms, specifically ML-DSA (Module-Lattice-Based Digital Signature Algorithm). This glossary provides comprehensive definitions and references for all technical terms, acronyms, and specifications used throughout the codebase and documentation.

The platform serves as both a demonstration environment and a development toolkit for exploring quantum-resistant authentication methods in real-world WebAuthn scenarios. Understanding these foundational concepts is essential for developers working with the platform or implementing similar solutions.

Core Acronyms and Definitions

Fundamental Authentication Terms

Authenticator: A hardware or software component that generates cryptographic keys and signs assertions. In this platform, authenticators support both classical and post-quantum cryptographic algorithms.

Relying Party (RP): The service provider that accepts WebAuthn authentication. The RP defines security policies and validates authentication results.

User: The individual whose identity is being authenticated through the WebAuthn process.

Credential: A cryptographic key pair associated with a user, used for authentication. Credentials can be resident (stored on the authenticator) or non-resident.

Assertion: A cryptographic proof generated by an authenticator that demonstrates possession of a private key corresponding to a public key in a registered credential.

Attestation: A process by which an authenticator cryptographically asserts its authenticity and security properties to a relying party.

Cryptographic Concepts

Resident Key: A credential that is stored persistently on the authenticator rather than being transmitted to the relying party. Resident keys enable passwordless authentication.

User Verification (UV): A requirement that the user must actively verify their identity through biometric or other interactive means before authentication can proceed.

Backup Eligibility: Indicates whether an authenticator supports backing up credentials to a cloud service or other external storage.

Extension: Additional functionality beyond the core WebAuthn specification, such as biometric authentication or large blob storage.

FIDO2/WebAuthn Specifications

WebAuthn Core Concepts

The WebAuthn specification (W3C Recommendation) defines the standardized interface between browsers and authenticators. Key components include:

• PublicKeyCredential: The fundamental data structure representing a WebAuthn credential
• AuthenticatorData: Binary encoding of authenticator state and metadata
• CollectedClientData: JSON-encoded client data containing challenge and origin information
• AttestationObject: Contains the attestation statement and authenticator data

Authenticator Data Structure

The AuthenticatorData class encapsulates the binary representation of authenticator state:

classDiagram
class AuthenticatorData {
+bytes rp_id_hash
+FLAG flags
+int counter
+AttestedCredentialData credential_data
+Mapping extensions
+is_user_present() bool
+is_user_verified() bool
+is_attested() bool
+has_extension_data() bool
}
class FLAG {
+UP : 0x01
+UV : 0x04
+BE : 0x08
+BS : 0x10
+AT : 0x40
+ED : 0x80
}
AuthenticatorData --> FLAG : contains

Loading

Diagram sources

• fido2/webauthn.py

Registration and Authentication Flows

The WebAuthn process involves two primary operations:

1. Registration: Creates a new credential and associates it with a user
2. Authentication: Verifies that the user possesses the private key corresponding to a registered credential

Section sources

• fido2/webauthn.py

CTAP2 Protocol Components

Client-to-Authenticator Protocol (CTAP2)

CTAP2 (FIDO Alliance Specification) defines the communication protocol between platforms and authenticators.

Core Commands

The Ctap2 class implements the main CTAP2 commands:

• MAKE_CREDENTIAL (0x01): Creates a new credential
• GET_ASSERTION (0x02): Generates an authentication assertion
• GET_INFO (0x04): Retrieves authenticator capabilities
• CLIENT_PIN (0x06): Manages PIN/UV authentication
• RESET (0x07): Erases all credentials and PIN
• GET_NEXT_ASSERTION (0x08): Retrieves additional assertions

Info Command Response

The Info class represents the authenticator capabilities:

classDiagram
class Info {
+str[] versions
+str[] extensions
+Aaguid aaguid
+dict~str,bool~ options
+int max_msg_size
+int[] pin_uv_protocols
+dict[] algorithms
+dict certifications
+get_identifier(pin_token) bytes
}
class Aaguid {
+str hex()
+str parse(value) Aaguid
+bool __bool__()
}
Info --> Aaguid : contains

Loading

Diagram sources

• fido2/ctap2/base.py

Response Objects

CTAP2 responses are structured using CBOR-encoded data objects:

• AttestationResponse: Contains attestation data for newly registered credentials
• AssertionResponse: Contains authentication data for verified credentials

Section sources

• fido2/ctap2/base.py

COSE and CBOR Standards

Concise Binary Object Representation (CBOR)

CBOR (RFC 8949) provides the binary encoding format for CTAP2 communications.

CBOR Implementation Features

The cbor.py module supports essential CBOR functionality:

• Canonical Encoding: Ensures consistent binary representation
• Type Support: Handles integers, booleans, strings, bytes, arrays, and maps
• Validation: Detects non-canonical encodings and extraneous data

COSE (CBOR Object Signing and Encryption)

COSE (RFC 8152) defines the structure for cryptographic messages using CBOR.

COSE Key Formats

The CoseKey class represents public keys in COSE format:

classDiagram
class CoseKey {
+int ALGORITHM
+verify(message, signature) void
+from_cryptography_key(key) CoseKey
+set_assertion_debug_data(auth_data, client_data) void
}
class MLDSA44 {
+int ALGORITHM = -48
+verify(message, signature) void
}
class MLDSA65 {
+int ALGORITHM = -49
+verify(message, signature) void
}
class MLDSA87 {
+int ALGORITHM = -50
+verify(message, signature) void
}
CoseKey <|-- MLDSA44
CoseKey <|-- MLDSA65
CoseKey <|-- MLDSA87

Loading

Diagram sources

• fido2/cose.py

Section sources

• fido2/cbor.py
• fido2/cose.py

Post-Quantum Cryptography

ML-DSA Algorithm Suite

The platform implements three ML-DSA variants as specified by NIST Post-Quantum Cryptography Standardization:

Algorithm Identifiers

Parameter Set	COSE Algorithm ID	Public Key Size	Signature Size
ML-DSA-44	-48	1312 bytes	2420 bytes
ML-DSA-65	-49	1952 bytes	3309 bytes
ML-DSA-87	-50	2592 bytes	4627 bytes

Implementation Details

The MLDSA44, MLDSA65, and MLDSA87 classes implement the respective ML-DSA variants:

sequenceDiagram
participant Client as Client Application
participant Authenticator as Authenticator
participant LibOQS as liboqs Library
Client->>Authenticator : Register Request
Authenticator->>LibOQS : Generate Key Pair
LibOQS-->>Authenticator : Public/Private Keys
Authenticator->>LibOQS : Sign Challenge
LibOQS-->>Authenticator : Signature
Authenticator-->>Client : Attestation Object
Client->>Authenticator : Authenticate Request
Authenticator->>LibOQS : Sign Challenge
LibOQS-->>Authenticator : Signature
Authenticator-->>Client : Assertion Response

Loading

Diagram sources

• fido2/cose.py
• server/pqc.py

PQC Algorithm Detection

The detect_available_pqc_algorithms function identifies available post-quantum algorithms:

flowchart TD
Start([Algorithm Detection]) --> LoadMechanisms["Load Enabled Mechanisms"]
LoadMechanisms --> CheckAvailable{"Check Available<br/>Algorithms"}
CheckAvailable --> |All Available| Success["Return Available IDs"]
CheckAvailable --> |Some Missing| ReportMissing["Report Missing Algorithms"]
ReportMissing --> ReturnPartial["Return Partial List"]
Success --> End([Complete])
ReturnPartial --> End

Loading

Diagram sources

• server/pqc.py

Section sources

• server/pqc.py
• prebuilt_liboqs/linux-x86_64/include/oqs/sig_ml_dsa.h

HID Transport Layer

Human Interface Device (HID) Protocol

HID provides the physical transport layer for CTAP2 communication between platforms and authenticators.

HID Descriptor Structure

The HidDescriptor class encapsulates device characteristics:

classDiagram
class HidDescriptor {
+str|bytes path
+int vid
+int pid
+int report_size_in
+int report_size_out
+str|None product_name
+str|None serial_number
}
class CtapHidConnection {
<<abstract>>
+read_packet() bytes
+write_packet(data) void
+close() void
}
class FileCtapHidConnection {
+CtapHidConnection handle
+HidDescriptor descriptor
}
CtapHidConnection <|-- FileCtapHidConnection
FileCtapHidConnection --> HidDescriptor : uses

Loading

Diagram sources

• fido2/hid/base.py

Report Descriptor Parsing

The parse_report_descriptor function extracts HID characteristics:

• Usage Page: FIDO_USAGE_PAGE (0xF1D0)
• Usage: FIDO_USAGE (0x01)
• Report Sizes: Input and output report sizes

Section sources

• fido2/hid/base.py

Metadata Service (MDS)

FIDO Metadata Service (MDS3)

The Metadata Service provides authenticator trustworthiness information and compliance data.

Metadata Statement Structure

The MetadataStatement class contains authenticator metadata:

classDiagram
class MetadataStatement {
+str description
+int authenticator_version
+int schema
+Version[] upv
+str[] attestation_types
+VerificationMethodDescriptor[] user_verification_details
+str[] key_protection
+str[] matcher_protection
+str[] attachment_hint
+bytes[] attestation_root_certificates
+Aaguid aaguid
+dict supported_extensions
}
class StatusReport {
+AuthenticatorStatus status
+date effective_date
+int authenticator_version
+bytes certificate
+str url
}
class AuthenticatorStatus {
<<enumeration>>
NOT_FIDO_CERTIFIED
FIDO_CERTIFIED
USER_VERIFICATION_BYPASS
ATTESTATION_KEY_COMPROMISE
REVOKED
}
MetadataStatement --> StatusReport : contains
StatusReport --> AuthenticatorStatus : uses

Loading

Diagram sources

• fido2/mds3.py

Attestation Verification

The MdsAttestationVerifier class validates authenticator attestations:

sequenceDiagram
participant RP as Relying Party
participant Verifier as MDS Verifier
participant MDS as Metadata Service
participant CA as Certificate Authority
RP->>Verifier : Verify Attestation
Verifier->>MDS : Lookup Authenticator
MDS-->>Verifier : Metadata Entry
Verifier->>CA : Verify Certificate Chain
CA-->>Verifier : Trust Path
Verifier-->>RP : Verification Result

Loading

Diagram sources

• fido2/mds3.py

Section sources

• fido2/mds3.py

Platform Implementation Details

Server Architecture

The platform consists of several key components:

Web Server

• Built on Flask framework
• HTTPS support with self-signed certificates
• WebSocket support for real-time updates

Client Interface

• JavaScript-based WebAuthn client
• Real-time decoding of CBOR responses
• Interactive demonstration of authentication flows

Authentication Flow

sequenceDiagram
participant Browser as Web Browser
participant Server as Web Server
participant Authenticator as Hardware Authenticator
participant PQC as Post-Quantum Crypto
Browser->>Server : Request Registration
Server-->>Browser : Registration Options
Browser->>Authenticator : Create Credential
Authenticator->>PQC : Generate ML-DSA Key
PQC-->>Authenticator : Key Pair
Authenticator-->>Browser : Attestation Object
Browser->>Server : Submit Attestation
Server->>Server : Verify Attestation
Server-->>Browser : Registration Complete
Browser->>Server : Request Authentication
Server-->>Browser : Authentication Options
Browser->>Authenticator : Get Assertion
Authenticator->>PQC : Sign Challenge
PQC-->>Authenticator : Signature
Authenticator-->>Browser : Assertion Response
Browser->>Server : Submit Assertion
Server->>Server : Verify Signature
Server-->>Browser : Authentication Complete

Loading

Diagram sources

• tests/test_mldsa_registration_authentication.py

Section sources

• README.adoc

Additional Reading Materials

FIDO Alliance Specifications

• WebAuthn Level 3: W3C Recommendation
• CTAP2 Specification: FIDO Alliance
• FIDO2 MDS3: FIDO Alliance

Standards and RFCs

• CBOR: RFC 8949
• COSE: RFC 8152
• JSON Web Algorithms: RFC 7518

Post-Quantum Cryptography Resources

• NIST Post-Quantum Cryptography Standardization: nist.gov
• Open Quantum Safe (OQS): openquantumsafe.org
• ML-DSA Specification: ML-DSA GitHub

Implementation References

• python-fido2: GitHub Repository
• liboqs: GitHub Repository
• liboqs-python: GitHub Repository

Security Considerations

When implementing post-quantum WebAuthn solutions, consider:

• Algorithm Selection: Choose appropriate ML-DSA variants based on security requirements
• Key Management: Implement proper key backup and recovery procedures
• Forward Secrecy: Ensure that quantum attacks cannot compromise previously captured data
• Performance Impact: Account for increased computational overhead of post-quantum algorithms
• Interoperability: Verify compatibility across different authenticator implementations

This glossary provides the foundation for understanding and implementing post-quantum WebAuthn authentication systems. The platform serves as both a learning resource and a production-ready solution for quantum-resistant authentication.