Data Schemas - FeitianTech/postquantum-webauthn-platform GitHub Wiki

Data Schemas

Table of Contents

  1. Introduction
  2. JSON Schema Architecture
  3. WebAuthn Data Classes
  4. CBOR Encoding for CTAP2 Messages
  5. Base64URL Encoding Conventions
  6. Browser WebAuthn API Transformations
  7. API Request and Response Payloads
  8. Schema Evolution and Backward Compatibility
  9. Validation and Error Handling
  10. Security Considerations

Introduction

The Post-Quantum WebAuthn Platform implements comprehensive data schema standards for secure authentication using quantum-resistant cryptographic algorithms. This documentation covers the complete data format ecosystem, including JSON schemas for API communications, CBOR encoding for CTAP2 protocol messages, and base64url encoding conventions for binary data transmission.

The platform supports both classical and post-quantum cryptographic algorithms, with automatic detection and selection of appropriate algorithms based on device capabilities and security requirements. All data formats are designed for interoperability with modern web browsers and authentication devices while maintaining security against quantum computing threats.

JSON Schema Architecture

The platform uses a sophisticated JSON schema system built around typed data classes that automatically handle serialization and deserialization between Python objects and JSON representations.

classDiagram
class _WebAuthnDataObject {
+__getitem__(key) Any
+from_dict(data) Self
+_parse_value(t, value) Any
}
class PublicKeyCredentialCreationOptions {
+rp : PublicKeyCredentialRpEntity
+user : PublicKeyCredentialUserEntity
+challenge : bytes
+pub_key_cred_params : Sequence[PublicKeyCredentialParameters]
+timeout : Optional[int]
+exclude_credentials : Optional[Sequence[PublicKeyCredentialDescriptor]]
+authenticator_selection : Optional[AuthenticatorSelectionCriteria]
+attestation : Optional[AttestationConveyancePreference]
+extensions : Optional[Mapping[str, Any]]
}
class PublicKeyCredentialRequestOptions {
+challenge : bytes
+timeout : Optional[int]
+rp_id : Optional[str]
+allow_credentials : Optional[Sequence[PublicKeyCredentialDescriptor]]
+user_verification : Optional[UserVerificationRequirement]
+extensions : Optional[Mapping[str, Any]]
}
class AuthenticatorAttestationResponse {
+client_data : CollectedClientData
+attestation_object : AttestationObject
+extension_results : Optional[Mapping[str, Any]]
}
class AuthenticatorAssertionResponse {
+client_data : CollectedClientData
+authenticator_data : AuthenticatorData
+signature : bytes
+user_handle : Optional[bytes]
+credential_id : Optional[bytes]
+extension_results : Optional[Mapping[str, Any]]
}
_WebAuthnDataObject <|-- PublicKeyCredentialCreationOptions
_WebAuthnDataObject <|-- PublicKeyCredentialRequestOptions
_WebAuthnDataObject <|-- AuthenticatorAttestationResponse
_WebAuthnDataObject <|-- AuthenticatorAssertionResponse

Diagram sources

Section sources

WebAuthn Data Classes

Core Data Types

The platform defines several fundamental data classes that represent different aspects of the WebAuthn protocol:

Attestation Objects

Attestation objects contain cryptographic evidence about the authenticator's capabilities and security properties. They follow the WebAuthn specification's attestation model while supporting post-quantum algorithms.

Authenticator Data

Authenticator data encapsulates the state and capabilities of the authentication device, including user presence flags, backup eligibility, and attested credential information.

Collected Client Data

Collected client data represents the JSON payload sent by the browser during WebAuthn operations, containing challenge information, origin details, and operation type.

Algorithm Support Matrix

The platform supports a comprehensive range of cryptographic algorithms:

Algorithm Family Classical Post-Quantum Identifier
Digital Signatures ES256 (ECDSA) ML-DSA-87, ML-DSA-65, ML-DSA-44 -7, -50, -49, -48
Asymmetric Encryption RS256 (RSA) Kyber, BIKE, FrodoKEM -257, -1, -2, -3
Key Agreement ECDH-ES SIKE, NTRU, Classic McEliece -25, -26, -27

Section sources

CBOR Encoding for CTAP2 Messages

The platform implements a minimal but comprehensive CBOR (Concise Binary Object Representation) implementation specifically tailored for FIDO 2 CTAP2 protocol messages.

flowchart TD
A["CBOR Input Data"] --> B["Type Detection"]
B --> C{"Data Type"}
C --> |Integer| D["dump_int()"]
C --> |Boolean| E["dump_bool()"]
C --> |String| F["dump_text()"]
C --> |Bytes| G["dump_bytes()"]
C --> |Array| H["dump_list()"]
C --> |Map| I["dump_dict()"]
D --> J["CBOR Encoded Output"]
E --> J
F --> J
G --> J
H --> J
I --> J
J --> K["CTAP2 Protocol Message"]

Diagram sources

CBOR Data Types Supported

The implementation supports the following CBOR data types essential for CTAP2 communication:

  • Unsigned integers (0-27): Basic integer encoding with varying byte lengths
  • Negative integers: Two's complement representation for negative values
  • Byte strings: Binary data with length prefixes
  • Text strings: UTF-8 encoded strings with length prefixes
  • Arrays: Ordered sequences with element counting
  • Maps: Key-value pairs with sorted key ordering

CTAP2 Command and Status Codes

The platform recognizes specific CTAP2 command and status codes:

Code Meaning Purpose
0x01 AuthenticatorMakeCredential Registration commands
0x02 AuthenticatorGetAssertion Authentication commands
0x00 Success status General success responses

Section sources

Base64URL Encoding Conventions

The platform employs base64url encoding for transmitting binary data in JSON contexts, following RFC 4648 standards with specific adaptations for WebAuthn applications.

sequenceDiagram
participant Binary as "Binary Data"
participant Encoder as "Base64URL Encoder"
participant Browser as "Browser API"
participant Server as "Server Backend"
Binary->>Encoder : Raw bytes
Encoder->>Encoder : urlsafe_b64encode()
Encoder->>Encoder : Remove padding ('=')
Encoder->>Encoder : Replace '+' with '-'
Encoder->>Encoder : Replace '/' with '_'
Encoder->>Browser : Base64URL string
Browser->>Server : JSON payload with base64url
Server->>Server : Decode base64url to bytes
Server->>Server : Process binary data

Diagram sources

Encoding Functions

The platform provides multiple encoding functions for different binary data scenarios:

websafe_encode()

Primary encoding function for general binary-to-text conversion, removing padding characters for compact representation.

websafe_decode()

Decoding counterpart that automatically handles padding restoration and character set conversion.

Custom Encoding Patterns

The platform supports various encoding patterns for different data types:

  • Hexadecimal encoding for identifiers
  • Base64 encoding for certificates
  • Base64URL encoding for WebAuthn payloads

Section sources

Browser WebAuthn API Transformations

The platform includes a sophisticated JavaScript library (webauthn-json.browser-ponyfill.js) that bridges the gap between browser WebAuthn APIs and the server-side data formats.

classDiagram
class WebAuthnJSONPonyfill {
+create(options) Promise~PublicKeyCredential~
+get(options) Promise~PublicKeyCredential~
+parseCreationOptionsFromJSON(json) Object
+parseRequestOptionsFromJSON(json) Object
+supported() boolean
}
class SchemaConverter {
+convert(conversionFn, schema, input) Object
+derived(schema, derive) Object
+required(schema) Object
+optional(schema) Object
}
class CredentialCreationOptions {
+publicKey : Object
+signal : Optional~AbortSignal~
}
class PublicKeyCredentialWithAttestation {
+type : string
+id : string
+rawId : ArrayBuffer
+authenticatorAttachment : Optional~string~
+response : Object
+clientExtensionResults : Object
}
WebAuthnJSONPonyfill --> SchemaConverter
SchemaConverter --> CredentialCreationOptions
SchemaConverter --> PublicKeyCredentialWithAttestation

Diagram sources

Schema Transformation Rules

The library applies specific transformation rules when converting between browser objects and JSON:

Automatic Conversions

  • Binary data fields are automatically converted using base64url encoding
  • Nested objects are recursively processed
  • Optional fields are preserved with null values

Field Mapping

  • rawId fields are converted from ArrayBuffer to base64url strings
  • clientDataJSON fields are processed as UTF-8 encoded JSON
  • Extension results are preserved with their native types

Section sources

API Request and Response Payloads

Registration Flow Payloads

Registration Begin Request

{
  "publicKey": {
    "rp": {
      "name": "Example Corporation",
      "id": "example.com"
    },
    "user": {
      "id": "base64url-encoded-user-id",
      "name": "[email protected]",
      "displayName": "John Doe"
    },
    "challenge": "base64url-encoded-challenge",
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": -50  // ML-DSA-87
      },
      {
        "type": "public-key",
        "alg": -7   // ES256
      }
    ],
    "timeout": 60000,
    "attestation": "direct",
    "authenticatorSelection": {
      "authenticatorAttachment": "cross-platform",
      "residentKey": "preferred",
      "userVerification": "preferred"
    }
  }
}

Registration Complete Response

{
  "id": "base64url-encoded-credential-id",
  "rawId": "base64url-encoded-raw-id",
  "type": "public-key",
  "response": {
    "attestationObject": "base64url-encoded-attestation-object",
    "clientDataJSON": "base64url-encoded-client-data-json"
  },
  "clientExtensionResults": {
    "credProps": {
      "rk": true
    }
  }
}

Authentication Flow Payloads

Authentication Begin Request

{
  "publicKey": {
    "challenge": "base64url-encoded-challenge",
    "rpId": "example.com",
    "allowCredentials": [
      {
        "id": "base64url-encoded-credential-id",
        "type": "public-key",
        "transports": ["usb", "nfc", "ble"]
      }
    ],
    "timeout": 60000,
    "userVerification": "preferred"
  }
}

Authentication Complete Response

{
  "id": "base64url-encoded-credential-id",
  "rawId": "base64url-encoded-raw-id",
  "type": "public-key",
  "response": {
    "authenticatorData": "base64url-encoded-authenticator-data",
    "clientDataJSON": "base64url-encoded-client-data-json",
    "signature": "base64url-encoded-signature",
    "userHandle": "base64url-encoded-user-handle"
  },
  "clientExtensionResults": {}
}

Section sources

Schema Evolution and Backward Compatibility

Version Management Strategy

The platform implements a robust schema evolution strategy that maintains backward compatibility while enabling forward-looking enhancements:

Semantic Versioning

  • Major versions indicate breaking changes requiring migration
  • Minor versions add new features with backward compatibility
  • Patch versions fix bugs without changing behavior

Migration Pathways

  • Automatic schema detection and adaptation
  • Graceful degradation for unsupported features
  • Progressive enhancement for newer capabilities

Compatibility Layers

Legacy Browser Support

The platform includes polyfills and compatibility shims for older browsers that lack native WebAuthn support:

// Feature detection and fallback mechanism
if (!window.PublicKeyCredential) {
    // Load ponyfill for legacy browser support
    loadWebAuthnPonyfill();
}

Algorithm Fallback Mechanisms

  • Primary algorithm selection based on device capability
  • Secondary algorithm fallback for compatibility
  • Automatic algorithm negotiation during registration

Section sources

Validation and Error Handling

Input Validation Pipeline

The platform implements multi-layered validation for all incoming data:

flowchart TD
A["Incoming Payload"] --> B["JSON Schema Validation"]
B --> C{"Valid JSON?"}
C --> |No| D["JSON Parse Error"]
C --> |Yes| E["Type Validation"]
E --> F{"Correct Types?"}
F --> |No| G["Type Error"]
F --> |Yes| H["Content Validation"]
H --> I{"Valid Content?"}
I --> |No| J["Content Error"]
I --> |Yes| K["Algorithm Validation"]
K --> L{"Supported Algorithms?"}
L --> |No| M["Algorithm Error"]
L --> |Yes| N["Processing Complete"]
D --> O["Error Response"]
G --> O
J --> O
M --> O

Error Response Formats

Standardized error responses follow a consistent format across all API endpoints:

{
  "error": "Specific error description",
  "code": "ERROR_CODE",
  "details": {
    "field": "problematic_field",
    "expected": "expected_value_type",
    "received": "actual_value"
  }
}

Common Error Conditions

Error Type Description Resolution
Invalid JSON Malformed JSON payload Validate JSON syntax
Missing Fields Required fields not present Check schema compliance
Type Mismatch Incorrect data types Verify field types
Algorithm Not Supported Unsupported cryptographic algorithm Use supported algorithms
Challenge Validation Invalid challenge format Regenerate challenge

Section sources

Security Considerations

Data Integrity Protection

The platform implements multiple layers of security protection for data integrity:

Cryptographic Hashing

  • SHA-256 hashing for challenge validation
  • HMAC-SHA256 for sensitive data protection
  • Algorithm agility for future-proofing

Input Sanitization

  • Comprehensive input validation for all payloads
  • Character encoding normalization
  • Binary data sanitization

Protocol Security

  • TLS encryption for all data transmission
  • Challenge replay protection
  • Session state management

Quantum Resistance Features

The platform incorporates quantum-resistant cryptographic primitives:

Post-Quantum Algorithms

  • ML-DSA signatures for digital signatures
  • Kyber key encapsulation for encryption
  • XOF-based randomness for enhanced security

Hybrid Approaches

  • Classical-quantum hybrid signatures
  • Dual algorithm support for graceful degradation
  • Automatic algorithm selection based on threat model

Section sources