Advanced Configuration Flow Endpoints - FeitianTech/postquantum-webauthn-platform GitHub Wiki

Advanced Configuration Flow Endpoints

Table of Contents

  1. Introduction
  2. Endpoint Overview
  3. Request/Response Schemas
  4. Advanced WebAuthn Features
  5. Algorithm Processing
  6. Credential Parsing
  7. Extension Parameters
  8. Security Considerations
  9. Examples
  10. Error Handling

Introduction

The Post-Quantum WebAuthn Platform provides advanced configuration flow endpoints that enable sophisticated WebAuthn operations with extensive customization capabilities. These endpoints support advanced features including custom algorithm selection, authenticator attachment preferences, resident key requirements, and comprehensive extension parameters.

The advanced flow endpoints are designed for developers who need fine-grained control over WebAuthn operations beyond the basic simple registration and authentication flows. They provide JSON editor support, custom credential parameters, and advanced attestation processing capabilities.

Endpoint Overview

The platform exposes four primary advanced configuration endpoints:

Endpoint Method Purpose
/api/advanced/register/begin POST Begin advanced credential registration with custom parameters
/api/advanced/register/complete POST Complete advanced credential registration with attestation
/api/advanced/authenticate/begin POST Begin advanced authentication with custom credential selection
/api/advanced/authenticate/complete POST Complete advanced authentication with assertion verification 
sequenceDiagram
participant Client as "Web Client"
participant Server as "Advanced API Server"
participant Authenticator as "Authenticator Device"
participant Storage as "Credential Storage"
Note over Client,Storage : Registration Flow
Client->>Server : POST /api/advanced/register/begin
Server-->>Client : Registration Options
Client->>Authenticator : Create Credential
Authenticator-->>Client : Registration Response
Client->>Server : POST /api/advanced/register/complete
Server->>Server : Validate Attestation
Server->>Storage : Store Credential
Server-->>Client : Registration Result
Note over Client,Storage : Authentication Flow
Client->>Server : POST /api/advanced/authenticate/begin
Server-->>Client : Authentication Options
Client->>Authenticator : Authenticate
Authenticator-->>Client : Assertion Response
Client->>Server : POST /api/advanced/authenticate/complete
Server->>Server : Verify Assertion
Server-->>Client : Authentication Result

Diagram sources

Request/Response Schemas

Registration Begin Endpoint

Request Schema:

{
  "publicKey": {
    "rp": {
      "id": "string",
      "name": "string"
    },
    "user": {
      "id": "string | object",
      "name": "string",
      "displayName": "string"
    },
    "challenge": "string",
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": "number | string"
      }
    ],
    "timeout": "number",
    "attestation": "none | direct | indirect | enterprise",
    "authenticatorSelection": {
      "authenticatorAttachment": "platform | cross-platform",
      "userVerification": "required | preferred | discouraged",
      "residentKey": "required | preferred | discouraged",
      "requireResidentKey": "boolean"
    },
    "excludeCredentials": [
      {
        "type": "public-key",
        "id": "string | object"
      }
    ],
    "extensions": {
      "credProps": "boolean",
      "minPinLength": "boolean",
      "credProtect": "number | string",
      "largeBlob": "object | string"
    },
    "hints": ["string"]
  }
}

Response Schema:

{
  "publicKey": {
    "challenge": "string",
    "rpId": "string",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "string"
      }
    ],
    "timeout": "number",
    "userVerification": "required | preferred | discouraged",
    "extensions": {
      "credProps": "boolean"
    }
  },
  "__session_state": "object",
  "warnings": ["string"]
}

Registration Complete Endpoint

Request Schema:

{
  "__credential_response": {
    "response": {
      "attestationObject": "string",
      "clientDataJSON": "string",
      "authenticatorData": "string",
      "transports": ["string"],
      "authenticatorAttachment": "platform | cross-platform"
    },
    "id": "string",
    "rawId": "string",
    "type": "public-key"
  },
  "__session_state": "object",
  "publicKey": {
    // Original request parameters
  }
}

Response Schema:

{
  "status": "OK",
  "algo": "string",
  "relyingParty": {
    "credentialId": "string",
    "publicKeyAlgorithm": "number",
    "attestationFormat": "string",
    "registrationData": {
      "authenticatorData": "string",
      "signatureCounter": "number",
      "flags": {
        "UP": "boolean",
        "UV": "boolean",
        "AT": "boolean",
        "BE": "boolean",
        "BS": "boolean",
        "ED": "boolean"
      }
    }
  },
  "storedCredential": {
    "credentialId": "string",
    "publicKeyAlgorithm": "number",
    "residentKey": "boolean",
    "authenticatorAttachment": "string"
  },
  "warnings": ["string"]
}

Authentication Begin Endpoint

Request Schema:

{
  "publicKey": {
    "challenge": "string",
    "timeout": "number",
    "userVerification": "required | preferred | discouraged",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "string | object"
      }
    ],
    "extensions": {
      "largeBlob": "object"
    },
    "hints": ["string"]
  },
  "storedCredentials": [
    {
      "credentialId": "string",
      "publicKey": "string",
      "resident": "boolean",
      "authenticatorAttachment": "platform | cross-platform"
    }
  ]
}

Response Schema:

{
  "publicKey": {
    "challenge": "string",
    "rpId": "string",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "string"
      }
    ],
    "timeout": "number",
    "userVerification": "required | preferred | discouraged"
  },
  "__session_state": "object"
}

Authentication Complete Endpoint

Request Schema:

{
  "__assertion_response": {
    "response": {
      "authenticatorData": "string",
      "clientDataJSON": "string",
      "signature": "string",
      "attestationObject": "string"
    },
    "id": "string",
    "rawId": "string",
    "type": "public-key"
  },
  "__session_state": "object",
  "publicKey": {
    // Original request parameters
  },
  "storedCredentials": [
    {
      "credentialId": "string",
      "publicKey": "string",
      "resident": "boolean"
    }
  ]
}

Response Schema:

{
  "status": "OK",
  "authenticatedCredentialId": "string",
  "signCount": "number",
  "algorithm": "number",
  "algorithmDescription": "string",
  "hintsUsed": ["string"]
}

Section sources

Advanced WebAuthn Features

Custom Algorithm Selection

The advanced endpoints support comprehensive algorithm selection with automatic coercion and validation:

flowchart TD
Start([Algorithm Input]) --> Coerce["Coerce to Integer"]
Coerce --> ParseString["Parse String Values"]
ParseString --> Lookup["Lookup Named Algorithms"]
Lookup --> Validate["Validate Algorithm"]
Validate --> Supported{"Supported?"}
Supported --> |Yes| Use["Use Algorithm"]
Supported --> |No| Custom{"Custom Algorithm?"}
Custom --> |Yes| Warn["Log Warning"]
Custom --> |No| Reject["Reject"]
Warn --> Use
Use --> End([Algorithm Ready])
Reject --> End

Diagram sources

The platform supports both standard and post-quantum cryptographic algorithms:

Algorithm Category Examples Status
Standard ECDSA ES256 (-7), ES384 (-35), ES512 (-36) Full Support
Standard RSA RS256 (-257), RS384 (-258), RS512 (-259) Full Support
Post-Quantum ML-DSA-87 (-50), ML-DSA-65 (-49), ML-DSA-44 (-48) Conditional Support
EdDSA Variants EdDSA (-8), Ed25519 (-19), Ed448 (-53) Full Support

Authenticator Attachment Preferences

The system supports flexible attachment preference handling:

  • Platform Authenticators: Built-in devices (touch ID, face ID, Windows Hello)
  • Cross-Platform Authenticators: External devices (USB, NFC, BLE)
  • Hint-Based Selection: Dynamic attachment resolution based on hints

Resident Key Requirements

Advanced resident key handling with multiple configuration options:

  • Required: Authenticator must support resident keys
  • Preferred: Prefer resident keys when available
  • Discouraged: Avoid resident keys if possible
  • Legacy Support: Backward compatibility with older configurations

Section sources

Algorithm Processing

Algorithm Coercion and Validation

The platform implements robust algorithm processing with multiple input formats:

classDiagram
class AlgorithmProcessor {
+coerce_cose_algorithm(value) int
+lookup_named_cose_algorithm(name) int
+normalize_algorithm_name_key(name) string
+is_custom_cose_algorithm(alg_id) bool
+describe_algorithm(alg_id) string
}
class AlgorithmValidation {
+validate_algorithm_support(alg_id) bool
+check_pqc_availability(alg_id) bool
+fallback_to_classical(alg_id) int
}
class AlgorithmLogging {
+log_algorithm_selection(stage, alg_id) void
+describe_algorithm(alg_id) string
}
AlgorithmProcessor --> AlgorithmValidation : "validates"
AlgorithmProcessor --> AlgorithmLogging : "logs"

Diagram sources

Post-Quantum Cryptography Support

The platform includes comprehensive post-quantum cryptography support:

  • ML-DSA Algorithms: ML-DSA-87, ML-DSA-65, ML-DSA-44
  • Falcon Signature: Falcon post-quantum signature scheme
  • Kyber KEM: Kyber key encapsulation mechanism
  • Sphincs+: Stateless hash-based signature scheme

Section sources

Credential Parsing

Multi-Format Support

The system supports multiple credential input formats:

flowchart TD
Input[Credential Input] --> TypeCheck{Input Type?}
TypeCheck --> |Object| Extract["Extract Properties"]
TypeCheck --> |String| Decode["Decode String"]
TypeCheck --> |Array| Parse["Parse Array"]
Extract --> Binary["Binary Extraction"]
Decode --> Base64["Base64 Decoding"]
Decode --> Hex["Hex Decoding"]
Binary --> Validate["Validate Format"]
Base64 --> Validate
Hex --> Validate
Validate --> Success["Valid Credential"]
Validate --> Error["Parsing Error"]

Diagram sources

Supported Formats

Format Example Description
Base64 URL eyJraWQiOiJ... Standard URL-safe base64 encoding
Base64 eyJraWQiOiJ... Standard base64 encoding with padding
Hex 0123456789abcdef Hexadecimal representation
Object with $base64url {"$base64url": "..."} Explicit format specification
Object with $base64 {"$base64": "..."} Explicit base64 format
Object with $hex {"$hex": "..."} Explicit hex format

Section sources

Extension Parameters

Available Extensions

The advanced endpoints support comprehensive WebAuthn extensions:

Extension Purpose Configuration
credProps Credential properties Boolean enable/disable
minPinLength Minimum PIN length Boolean enable/disable
credProtect Credential protection policy Policy level (1-3)
largeBlob Large blob storage Read/write configuration
prf Private key reduction Evaluation parameters

Extension Processing

sequenceDiagram
participant Client as "Client Request"
participant Server as "Extension Processor"
participant Authenticator as "Authenticator"
Client->>Server : Request with Extensions
Server->>Server : Process Extension Config
Server->>Authenticator : Send Extension Data
Authenticator-->>Server : Extension Results
Server->>Server : Validate Results
Server-->>Client : Final Response

Diagram sources

Section sources

Security Considerations

Input Validation

The platform implements comprehensive input validation:

  1. Algorithm Validation: Ensures algorithms are supported and valid
  2. Binary Format Validation: Validates encoding formats (base64, hex)
  3. Parameter Sanitization: Sanitizes user-provided parameters
  4. Session State Protection: Validates session state integrity

Custom Algorithm Handling

When dealing with custom COSE algorithms:

  • Warning Logging: Logs when custom algorithms are encountered
  • Fallback Mechanism: Falls back to classical algorithms when needed
  • Signature Verification: May bypass signature verification for custom algorithms
  • Audit Trail: Maintains audit trail for security monitoring

Attestation Security

Advanced attestation processing includes:

  • Root Certificate Validation: Validates attestation chain
  • AAGUID Matching: Verifies authenticator identification
  • RP ID Hash Validation: Ensures proper relying party binding
  • Metadata Verification: Uses FIDO Metadata Service for authenticator validation

Section sources

Examples

Basic Registration with Custom Algorithm

{
  "publicKey": {
    "rp": {
      "id": "example.com",
      "name": "Example Application"
    },
    "user": {
      "id": "user123",
      "name": "[email protected]",
      "displayName": "Alice Johnson"
    },
    "challenge": "dGhlIHNhbXBsZSBjb250ZXh0",
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": "-50"  // ML-DSA-87
      }
    ],
    "authenticatorSelection": {
      "authenticatorAttachment": "platform",
      "userVerification": "required",
      "residentKey": "preferred"
    },
    "attestation": "direct",
    "extensions": {
      "credProps": true,
      "largeBlob": {
        "write": "blob-data-hex"
      }
    }
  }
}

Advanced Authentication with Credential Selection

{
  "publicKey": {
    "challenge": "dGhlIHNhbXBsZSBjb250ZXh0",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "specific-credential-id"
      }
    ],
    "userVerification": "preferred",
    "extensions": {
      "largeBlob": {
        "read": true
      }
    },
    "hints": ["platform", "cross-platform"]
  },
  "storedCredentials": [
    {
      "credentialId": "credential123",
      "publicKey": "base64-public-key",
      "resident": true,
      "authenticatorAttachment": "platform"
    }
  ]
}

JSON Editor Integration

The platform includes a JSON editor for advanced configuration:

// Example JSON editor configuration
const editorConfig = {
  registration: {
    rp: { id: "example.com", name: "Example App" },
    user: { id: "user123", name: "alice", displayName: "Alice" },
    challenge: "base64-challenge",
    pubKeyCredParams: [{ type: "public-key", alg: -50 }],
    authenticatorSelection: {
      authenticatorAttachment: "platform",
      userVerification: "required"
    }
  }
};

Section sources

Error Handling

Common Error Responses

Error Code Message Cause
400 "Invalid request: Missing publicKey" Missing required publicKey field
400 "Credential response is required" Missing credential response
400 "Authentication state not found" Expired session state
404 "No credentials detected" No stored credentials available
400 "Invalid challenge format" Malformed challenge parameter

Error Recovery Strategies

  1. Session State Recovery: Attempts to recover from expired states
  2. Algorithm Fallback: Falls back to supported algorithms when custom ones fail
  3. Credential Refresh: Provides guidance for credential refresh when needed
  4. Validation Feedback: Detailed error messages for debugging

Debug Information

The platform provides comprehensive debug information:

{
  "debugInfo": {
    "algorithmsUsed": [-50, -49],
    "attestationFormat": "packed",
    "hintsUsed": ["platform"],
    "algorithm": -50,
    "algorithmDescription": "ML-DSA-87 (PQC)",
    "customAlgorithmBypass": false
  }
}

Section sources