-
Notifications
You must be signed in to change notification settings - Fork 0
Advanced Configuration & Management
- Introduction
- System Architecture Overview
- Core Configuration Endpoints
- Credential Management System
- Large Blob Storage Implementation
- Metadata Service Integration
- CTAP2 Extension Framework
- Security Configuration Management
- Authentication and Authorization
- Troubleshooting and Error Handling
- Performance Considerations
- Best Practices
The advanced configuration and management system provides comprehensive functionality for WebAuthn authenticator administration, extending beyond basic credential operations to include sophisticated features like authenticator configuration, credential management, large blob storage, and metadata inspection. This system serves as a bridge between WebAuthn standards and practical authenticator administration, offering both programmatic and interactive interfaces for managing authenticator capabilities.
The system is built around several key components:
- Configuration Management: Control authenticator settings like PIN policies, UV requirements, and enterprise attestation
- Credential Management: Advanced credential lifecycle operations including enumeration, deletion, and updates
- Extension Framework: Support for CTAP2 extensions including PRF, bioEnroll, and custom extensions
- Large Blob Storage: Secure storage of arbitrary data associated with credentials
- Metadata Service: Integration with FIDO Metadata Service for authenticator information
- Security Controls: Comprehensive PIN/UV authentication and permission management
The advanced configuration system follows a layered architecture that separates concerns between presentation, business logic, and hardware communication:
graph TB
subgraph "Presentation Layer"
UI[Web Interface]
API[REST API Endpoints]
end
subgraph "Business Logic Layer"
ADV[Advanced Routes]
EXT[Extension Handlers]
SEC[Security Manager]
end
subgraph "Service Layer"
CFG[Config Service]
CRED[Credential Service]
BLOB[Large Blob Service]
MDS[Metadata Service]
end
subgraph "Hardware Abstraction Layer"
CTAP2[CTAP2 Commands]
HID[HID Transport]
end
subgraph "Storage Layer"
FS[File System]
CACHE[Memory Cache]
METADATA[Metadata Cache]
end
UI --> API
API --> ADV
ADV --> EXT
ADV --> SEC
EXT --> CFG
EXT --> CRED
EXT --> BLOB
CFG --> CTAP2
CRED --> CTAP2
BLOB --> CTAP2
MDS --> METADATA
CTAP2 --> HID
ADV --> FS
ADV --> CACHE
Diagram sources
- advanced.py
- config.py
- base.py
Section sources
- advanced.py
- base.py
The configuration endpoint provides access to authenticator configuration capabilities through the CTAP2 Config API. This endpoint supports various configuration operations including enterprise attestation, PIN policies, and UV requirements.
sequenceDiagram
participant Client as Client Application
participant API as /config Endpoint
participant Config as Config Service
participant CTAP2 as CTAP2 Command
participant Auth as Authenticator
Client->>API : POST /config
API->>API : Validate PIN/UV Token
API->>Config : Configure Operation
Config->>CTAP2 : Send Config Command
CTAP2->>Auth : Execute CTAP2 Config
Auth-->>CTAP2 : Configuration Result
CTAP2-->>Config : Response Data
Config-->>API : Formatted Response
API-->>Client : Configuration Status
Diagram sources
- config.py
- advanced.py
The system supports several configuration operations:
| Operation | Purpose | Security Level |
|---|---|---|
| Enable Enterprise Attestation | Allow enterprise attestation certificates | High |
| Toggle Always UV | Require UV for all operations | High |
| Set Minimum PIN Length | Configure PIN length requirements | Medium |
| Force PIN Change | Require PIN change on next use | Medium |
Enable Enterprise Attestation Request:
{
"operation": "enable-enterprise-attestation",
"pinToken": "base64-encoded-token",
"permissions": ["authenticator-config"]
}
Configuration Response:
{
"status": "success",
"operation": "enable-enterprise-attestation",
"timestamp": "2024-01-15T10:30:00Z",
"configuration": {
"enterpriseAttestationEnabled": true,
"requiresUVForConfig": false
}
}
Section sources
- config.py
- advanced.py
The credential management endpoint provides comprehensive credential lifecycle operations including enumeration, deletion, and updates. This endpoint integrates with the CTAP2 Credential Management API to provide advanced credential administration capabilities.
flowchart TD
Start([Credential Management Request]) --> ValidateAuth["Validate Authentication"]
ValidateAuth --> CheckOperation{"Operation Type"}
CheckOperation --> |Enumerate| EnumBegin["Begin Enumeration"]
CheckOperation --> |Delete| DeleteCred["Delete Credential"]
CheckOperation --> |Update| UpdateCred["Update User Info"]
EnumBegin --> EnumNext["Get Next Entry"]
EnumNext --> HasMore{"More Entries?"}
HasMore --> |Yes| EnumNext
HasMore --> |No| ReturnResults["Return Results"]
DeleteCred --> ValidateCred["Validate Credential ID"]
ValidateCred --> RemoveEntry["Remove from Storage"]
RemoveEntry --> UpdateCount["Update Metadata"]
UpdateCred --> ValidateUpdate["Validate Update Data"]
ValidateUpdate --> ModifyEntry["Modify User Info"]
ModifyEntry --> UpdateCount
ReturnResults --> End([End])
UpdateCount --> End
Diagram sources
- credman.py
- advanced.py
Enumerate Resident Credentials:
{
"operation": "enumerate-credentials",
"rpIdHash": "sha256-hash-of-rp-id",
"startIndex": 0,
"pageSize": 10
}
Delete Credential:
{
"operation": "delete-credential",
"credentialId": "base64-url-encoded-id",
"pinToken": "base64-encoded-token"
}
Update User Information:
{
"operation": "update-user-info",
"credentialId": "base64-url-encoded-id",
"newUserInfo": {
"name": "updated-name",
"displayName": "Updated Display Name",
"icon": "data:image/png;base64,..."
},
"pinToken": "base64-encoded-token"
}
Section sources
- credman.py
- advanced.py
The advanced registration system provides sophisticated credential creation capabilities with extensive customization options for authenticator behavior and extension support.
sequenceDiagram
participant Client as Web Client
participant Server as Advanced Server
participant Auth as Authenticator
participant Storage as Credential Store
Client->>Server : Register Begin Request
Server->>Server : Parse Registration Options
Server->>Server : Validate Extensions
Server->>Auth : Send Make Credential Request
Auth->>Auth : Process Registration
Auth-->>Server : Attestation Response
Server->>Server : Verify Attestation
Server->>Storage : Store Credential
Server-->>Client : Registration Complete
Diagram sources
- advanced.py
- advanced.py
The system maintains comprehensive credential artifacts with metadata, allowing for detailed credential management and audit capabilities.
Credential Artifact Structure:
{
"schemaVersion": 1,
"storedCredential": {
"type": "advanced",
"userName": "user@example.com",
"displayName": "User Display Name",
"residentKey": true,
"largeBlob": false,
"authenticatorAttachment": "cross-platform",
"credentialId": "base64-url-encoded-id",
"publicKeyAlgorithm": -7,
"signCount": 0,
"createdAt": "2024-01-15T10:30:00Z",
"properties": {
"attestationChecks": {...},
"authenticatorExtensions": {...},
"largeBlobRequested": {...}
}
}
}
Section sources
- advanced.py
- advanced.py
The large blob storage system provides secure, encrypted storage for arbitrary data associated with WebAuthn credentials, supporting both read and write operations with proper access controls.
classDiagram
class LargeBlobs {
+ctap : Ctap2
+max_fragment_length : int
+pin_uv : PinUv
+read_blob_array() Sequence[Mapping]
+write_blob_array(blob_array : Sequence) void
+get_blob(large_blob_key : bytes) bytes
+put_blob(large_blob_key : bytes, data : bytes) void
+delete_blob(large_blob_key : bytes) void
}
class BlobEncryption {
+encrypt(data : bytes, key : bytes) dict
+decrypt(encrypted : dict, key : bytes) bytes
+compress(data : bytes) bytes
+decompress(compressed : bytes) bytes
}
class AccessControl {
+validate_permissions(token : bytes) bool
+check_write_access(credential_id : bytes) bool
+check_read_access(credential_id : bytes) bool
}
LargeBlobs --> BlobEncryption : uses
LargeBlobs --> AccessControl : validates
Diagram sources
- blob.py
- blob.py
The large blob system uses AES-GCM encryption with SHA-256 authentication data for secure storage:
Encryption Process:
- Compression: Data is compressed using zlib with negative wbits
- Encryption: Compressed data is encrypted using AES-GCM with 12-byte nonce
- Authentication: SHA-256 authentication data includes "blob" prefix and original size
- Storage: Encrypted data, nonce, and original size are stored together
Access Control Flow:
flowchart TD
Request[Large Blob Request] --> ValidateToken["Validate PIN/UV Token"]
ValidateToken --> CheckPermissions{"Check Permissions"}
CheckPermissions --> |Write Operation| ValidateWrite["Validate Write Permission"]
CheckPermissions --> |Read Operation| ValidateRead["Validate Read Permission"]
ValidateWrite --> EncryptData["Encrypt Data"]
ValidateRead --> DecryptData["Decrypt Data"]
EncryptData --> StoreBlob["Store in Blob Array"]
DecryptData --> ReturnData["Return Decrypted Data"]
StoreBlob --> Success["Success Response"]
ReturnData --> Success
Diagram sources
- blob.py
- blob.py
Section sources
- blob.py
The system integrates with the FIDO Metadata Service to provide authenticator information, compliance status, and capability details.
graph LR
subgraph "Metadata Service"
MDS[FIDO MDS]
Verified[Verified Snapshot]
Cache[Local Cache]
end
subgraph "Application Layer"
MDSHandler[MDS Handler]
AuthInfo[Authenticator Info]
Compliance[Compliance Check]
end
subgraph "Storage"
Session[Session Metadata]
Local[Local Storage]
end
MDS --> Verified
Verified --> Cache
Cache --> MDSHandler
MDSHandler --> AuthInfo
MDSHandler --> Compliance
AuthInfo --> Session
Compliance --> Local
Diagram sources
- general.py
- mds3.py
Retrieve Authenticator Information:
{
"operation": "get-authenticator-info",
"aaguid": "12345678-1234-1234-1234-123456789abc"
}
Metadata Response:
{
"status": "success",
"authenticatorInfo": {
"aaguid": "12345678-1234-1234-1234-123456789abc",
"manufacturer": "Example Corp",
"model": "Secure Authenticator 2000",
"complianceVersion": "1.0",
"statusReports": [
{
"status": "FIDO_CERTIFIED",
"effectiveDate": "2024-01-01"
}
],
"authenticationAlgorithms": [-7, -257],
"attestationTypes": ["basic"]
}
}
Section sources
- general.py
- mds3.py
The CTAP2 extension framework provides a flexible system for supporting WebAuthn extensions with proper negotiation, processing, and authentication.
classDiagram
class Ctap2Extension {
<<abstract>>
+is_supported(ctap : Ctap2) bool
+make_credential(ctap : Ctap2, options : dict) ExtensionProcessor
+get_assertion(ctap : Ctap2, options : dict) ExtensionProcessor
}
class ExtensionProcessor {
<<abstract>>
+prepare_inputs(pin_token : bytes) dict
+prepare_outputs(response : dict, pin_token : bytes) dict
}
class RegistrationProcessor {
+prepare_inputs(pin_token : bytes) dict
+prepare_outputs(response : dict, pin_token : bytes) dict
}
class AuthenticationProcessor {
+prepare_inputs(selected : dict, pin_token : bytes) dict
+prepare_outputs(response : dict, pin_token : bytes) dict
}
class HmacSecretExtension {
+allow_hmac_secret : bool
+make_credential(ctap, options, protocol) RegistrationProcessor
+get_assertion(ctap, options, protocol) AuthenticationProcessor
}
class LargeBlobExtension {
+make_credential(ctap, options, protocol) RegistrationProcessor
+get_assertion(ctap, options, protocol) AuthenticationProcessor
}
Ctap2Extension <|-- HmacSecretExtension
Ctap2Extension <|-- LargeBlobExtension
ExtensionProcessor <|-- RegistrationProcessor
ExtensionProcessor <|-- AuthenticationProcessor
Ctap2Extension --> ExtensionProcessor : creates
Diagram sources
- extensions.py
- extensions.py
The PRF extension enables applications to derive secrets from authenticator-provided entropy:
PRF Configuration:
{
"prf": {
"eval": {
"first": "base64-encoded-salt1",
"second": "base64-encoded-salt2"
}
}
}
PRF Response:
{
"prf": {
"enabled": true,
"results": {
"first": "base64-derived-secret1",
"second": "base64-derived-secret2"
}
}
}
The HMAC Secret extension provides secure secret storage and retrieval:
HMAC Secret Configuration:
{
"hmacCreateSecret": true,
"hmacGetSecret": {
"salt1": "base64-salt1",
"salt2": "base64-salt2"
}
}
Section sources
- extensions.py
The system implements comprehensive PIN/UV authentication with multiple protocol versions and permission-based access control.
sequenceDiagram
participant App as Application
participant ClientPin as Client PIN
participant Protocol as PIN Protocol
participant Auth as Authenticator
App->>ClientPin : Request PIN Token
ClientPin->>Protocol : Generate Key Agreement
Protocol->>Auth : GET_KEY_AGREEMENT
Auth-->>Protocol : Public Key
Protocol-->>ClientPin : Shared Secret
ClientPin->>Protocol : Encrypt PIN Hash
ClientPin->>Protocol : Authenticate Message
ClientPin->>Auth : GET_TOKEN_USING_PIN
Auth-->>ClientPin : Encrypted Token
ClientPin-->>App : Decrypted Token
Diagram sources
- pin.py
- pin.py
The permission system provides fine-grained access control for different operations:
| Permission | Description | Scope |
|---|---|---|
| MAKE_CREDENTIAL | Create new credentials | Global |
| GET_ASSERTION | Authenticate with credentials | Global |
| CREDENTIAL_MGMT | Manage existing credentials | Global |
| BIO_ENROLL | Biometric enrollment | Global |
| LARGE_BLOB_WRITE | Write large blobs | Per-credential |
| AUTHENTICATOR_CFG | Configure authenticator | Global |
| PERSISTENT_CREDENTIAL_MGMT | Persistent credential management | Global |
Permission Validation Flow:
flowchart TD
Operation[Operation Request] --> ExtractToken["Extract PIN/UV Token"]
ExtractToken --> ValidateToken["Validate Token Format"]
ValidateToken --> CheckPermissions["Check Required Permissions"]
CheckPermissions --> HasPermission{"Has Permission?"}
HasPermission --> |Yes| ExecuteOperation["Execute Operation"]
HasPermission --> |No| DenyAccess["Deny Access"]
ExecuteOperation --> LogAccess["Log Access"]
DenyAccess --> ErrorResponse["Return Error"]
LogAccess --> Success["Success Response"]
ErrorResponse --> End([End])
Success --> End
Diagram sources
- pin.py
- advanced.py
Section sources
- pin.py
The system supports various authentication factors including PIN, biometric verification, and UV tokens:
graph TD
subgraph "Authentication Factors"
PIN[PIN/Password]
UV[User Verification]
BIOMETRIC[Biometric]
TOKEN[UV Token]
end
subgraph "Authentication Methods"
PIN_AUTH[PIN Authentication]
UV_AUTH[UV Authentication]
BIOMETRIC_AUTH[Biometric Authentication]
end
subgraph "Authorization Levels"
BASIC[Basic Access]
ADMIN[Administrative Access]
CONFIG[Configuration Access]
end
PIN --> PIN_AUTH
UV --> UV_AUTH
BIOMETRIC --> BIOMETRIC_AUTH
TOKEN --> UV_AUTH
PIN_AUTH --> BASIC
UV_AUTH --> ADMIN
BIOMETRIC_AUTH --> ADMIN
PIN_AUTH --> CONFIG
The system implements secure session management with automatic cleanup and state persistence:
Session State Management:
# Session storage for registration state
session["advanced_state"] = registration_state
session["advanced_rp"] = relying_party_info
session["advanced_original_request"] = original_request_data
# Session storage for authentication state
session["advanced_auth_state"] = authentication_state
session["advanced_auth_rp"] = relying_party_info
session["advanced_auth_credentials_meta"] = credential_metadata
Section sources
- advanced.py
- advanced.py
Issue: Configuration changes not taking effect Cause: Insufficient permissions or invalid PIN/UV token Solution: Verify PIN/UV authentication and required permissions
Error Response:
{
"error": "Configuration update failed",
"details": "Insufficient permissions for operation",
"requiredPermissions": ["authenticator-config"],
"errorCode": "INSUFFICIENT_PERMISSIONS"
}
Issue: Authenticator state mismatch between client and server Cause: Network interruption during operation or concurrent access Solution: Implement retry logic with exponential backoff
Recovery Flow:
flowchart TD
Error[Operation Error] --> CheckRetry{"Can Retry?"}
CheckRetry --> |Yes| WaitDelay["Wait with Backoff"]
CheckRetry --> |No| ReportError["Report Error"]
WaitDelay --> RetryOp["Retry Operation"]
RetryOp --> Success{"Success?"}
Success --> |Yes| Complete["Complete"]
Success --> |No| CheckRetry
ReportError --> UserAction["User Action Required"]
Complete --> End([End])
UserAction --> End
Issue: Extensions not supported by authenticator Cause: Authenticator firmware limitations or disabled features Solution: Graceful degradation with fallback mechanisms
Extension Fallback Strategy:
def negotiate_extension_support(extensions, authenticator_info):
supported_extensions = {}
for ext_name, ext_config in extensions.items():
if ext_name in authenticator_info.get("extensions", []):
supported_extensions[ext_name] = ext_config
else:
logger.warning(f"Extension {ext_name} not supported by authenticator")
# Apply fallback or skip extension
return supported_extensions
Section sources
- advanced.py
- extensions.py
For large blob operations, the system implements chunked transfer with configurable fragment sizes:
class LargeBlobs:
def __init__(self, ctap, pin_protocol=None, pin_token=None):
self.max_fragment_length = self.ctap.info.max_msg_size - 64
# Reserve 64 bytes for overhead in each fragment
The metadata service implements intelligent caching with automatic refresh:
- Cache Duration: 24 hours for verified metadata
- Refresh Trigger: On-demand or when cache expires
- Fallback: Use cached data during network failures
For large credential sets, the system supports pagination:
def enumerate_credentials_paginated(rp_id_hash, page_size=100):
offset = 0
while True:
batch = ctap.credential_management(
CMD.ENUMERATE_CREDS_BEGIN,
{PARAM.RP_ID_HASH: rp_id_hash, PARAM.OFFSET: offset},
page_size
)
yield batch
if len(batch) < page_size:
break
offset += page_size
The system implements careful memory management for large operations:
- Streaming Processing: Process large datasets in chunks
- Garbage Collection: Explicit cleanup of sensitive data
- Resource Limits: Configurable limits on concurrent operations
- Principle of Least Privilege: Always request minimal required permissions
- Secure PIN Management: Implement proper PIN validation and rate limiting
- Audit Logging: Log all configuration changes and administrative operations
- Data Encryption: Use strong encryption for sensitive data at rest and in transit
- Monitoring: Implement comprehensive monitoring for system health
- Backup: Regular backup of configuration and credential data
- Testing: Thorough testing of configuration changes in staging environments
- Documentation: Maintain up-to-date documentation for all configurations
- Error Handling: Implement comprehensive error handling and user feedback
- Validation: Validate all inputs and configuration parameters
- Compatibility: Test with multiple authenticator models and firmware versions
- Performance: Monitor and optimize for typical usage patterns
The advanced configuration and management system provides a robust foundation for WebAuthn authenticator administration, combining security, flexibility, and ease of use to support complex deployment scenarios while maintaining compliance with WebAuthn standards and best practices.