Authenticator Configuration - FeitianTech/postquantum-webauthn-platform GitHub Wiki
Authenticator Configuration Extension
Table of Contents
- Introduction
- Architecture Overview
- Configuration Command Structure
- Parameter Encoding via CBOR
- State Persistence Mechanisms
- Security Implementation
- Integration with Extensions Framework
- Test Examples and Validation
- Error Handling and Validation
- Troubleshooting Guide
- Conclusion
Introduction
The Authenticator Configuration extension provides a comprehensive API for managing authenticator features and security policies through CTAP2.1 commands. This extension enables administrators to configure enterprise attestation, adjust minimum PIN length requirements, toggle always-user-verification settings, and manage credential protection policies. The implementation follows strict security protocols with PIN/UV authentication, CBOR encoding standards, and robust error handling mechanisms.
The configuration system operates through a structured command interface that supports both immediate configuration changes and persistent state management. All configuration modifications require appropriate authentication tokens and are subject to comprehensive validation to prevent privilege escalation attacks.
Architecture Overview
The Authenticator Configuration extension is built around a modular architecture that separates concerns between command processing, authentication, and state management:
classDiagram
class Config {
+Ctap2 ctap
+PinProtocol pin_uv
+is_supported(info) bool
+enable_enterprise_attestation() void
+toggle_always_uv() void
+set_min_pin_length() void
+_call(sub_cmd, params) dict
}
class CMD {
+ENABLE_ENTERPRISE_ATT 0x01
+TOGGLE_ALWAYS_UV 0x02
+SET_MIN_PIN_LENGTH 0x03
+VENDOR_PROTOTYPE 0xFF
}
class PARAM {
+NEW_MIN_PIN_LENGTH 0x01
+MIN_PIN_LENGTH_RPIDS 0x02
+FORCE_CHANGE_PIN 0x03
}
class Ctap2 {
+config(sub_cmd, params, pin_uv_protocol, pin_uv_param) dict
+send_cbor(cmd, args) dict
}
class PinProtocol {
+VERSION int
+authenticate(key, message) bytes
+encrypt(key, plaintext) bytes
+decrypt(key, ciphertext) bytes
}
Config --> CMD : uses
Config --> PARAM : uses
Config --> Ctap2 : communicates
Config --> PinProtocol : authenticates
Ctap2 --> PinProtocol : utilizes
Diagram sources
Section sources
Configuration Command Structure
The configuration system implements four primary commands defined in the CMD enumeration:
Enterprise Attestation Management
The ENABLE_ENTERPRISE_ATT command (0x01) manages enterprise attestation capabilities. When enabled, authenticators can issue enterprise-validated certificates for credentials, supporting organizational attestation requirements.
User Verification Control
The TOGGLE_ALWAYS_UV command (0x02) modifies the always-UV setting, requiring user verification for every credential assertion when activated. This enhances security by eliminating scenarios where user presence alone suffices for authentication.
PIN Length Configuration
The SET_MIN_PIN_LENGTH command (0x03) adjusts minimum PIN length requirements with sophisticated parameter handling:
flowchart TD
Start([Configuration Request]) --> ValidateSupported{"Support Check"}
ValidateSupported --> |Not Supported| Error1["Return UNSUPPORTED_OPTION"]
ValidateSupported --> |Supported| ValidateAuth{"Authentication Check"}
ValidateAuth --> |Missing| Error2["Return PIN_REQUIRED"]
ValidateAuth --> |Present| ParseParams["Parse Parameters"]
ParseParams --> ValidateLength{"Length Validation"}
ValidateLength --> |Invalid| Error3["Return PIN_POLICY_VIOLATION"]
ValidateLength --> |Valid| ApplyChanges["Apply Configuration"]
ApplyChanges --> PersistState["Persist to Storage"]
PersistState --> UpdateInfo["Update Info Object"]
UpdateInfo --> Success([Configuration Applied])
Error1 --> End([Command Complete])
Error2 --> End
Error3 --> End
Success --> End
Diagram sources
Section sources
Parameter Encoding via CBOR
All configuration parameters are encoded using CBOR (Concise Binary Object Representation) with strict canonical ordering requirements. The parameter structure follows a hierarchical approach:
Parameter Structure
Configuration parameters are organized using the PARAM enumeration:
| Parameter | Value | Description |
|---|---|---|
| NEW_MIN_PIN_LENGTH | 0x01 | Specifies the new minimum PIN length requirement |
| MIN_PIN_LENGTH_RPIDS | 0x02 | Defines relying party identifiers for PIN length queries |
| FORCE_CHANGE_PIN | 0x03 | Indicates whether PIN change enforcement is required |
CBOR Encoding Process
The CBOR encoding process ensures deterministic serialization and security:
sequenceDiagram
participant Client as "Configuration Client"
participant Encoder as "CBOR Encoder"
participant Validator as "Parameter Validator"
participant Authenticator as "Authenticator"
Client->>Encoder : Parameters Dictionary
Encoder->>Encoder : Sort Keys Canonically
Encoder->>Validator : Encoded CBOR Data
Validator->>Validator : Validate Structure
Validator->>Authenticator : Validated Parameters
Authenticator->>Authenticator : Process Configuration
Authenticator-->>Client : Configuration Response
Diagram sources
The encoding process handles various data types with specific serialization rules:
- Integers: Encoded with minimal byte representation
- Strings: UTF-8 encoded with length prefixes
- Arrays: Ordered sequences with length indicators
- Maps: Canonical key ordering with deterministic serialization
Section sources
State Persistence Mechanisms
Configuration state persistence involves multiple layers of storage and validation:
Storage Architecture
Configuration changes are persisted through a multi-tier system:
- Runtime State: Immediate configuration updates in authenticator memory
- Persistent Storage: Non-volatile storage for configuration retention
- Validation Layer: Parameter validation before persistence
- Audit Trail: Logging of configuration changes for security monitoring
Persistence Workflow
flowchart TD
ValidateChange["Validate Change Request"] --> UpdateMemory["Update Runtime Memory"]
UpdateMemory --> ValidatePersistence{"Persistence Check"}
ValidatePersistence --> |Success| WriteStorage["Write to Persistent Storage"]
ValidatePersistence --> |Failure| RollbackMemory["Rollback Memory State"]
WriteStorage --> UpdateInfoObject["Update Info Object"]
UpdateInfoObject --> NotifyClients["Notify Affected Clients"]
NotifyClients --> Success([Persistence Complete])
RollbackMemory --> NotifyError["Notify Error"]
NotifyError --> Failure([Persistence Failed])
Diagram sources
Section sources
Security Implementation
The configuration system implements comprehensive security measures to prevent unauthorized access and privilege escalation:
Authentication Framework
Configuration changes require PIN/UV authentication through the established PIN/UV protocol:
sequenceDiagram
participant Client as "Configuration Client"
participant Auth as "Authentication Module"
participant Crypto as "Cryptographic Engine"
participant Storage as "Secure Storage"
Client->>Auth : Configuration Request + Token
Auth->>Crypto : Generate Challenge
Crypto-->>Auth : Challenge Response
Auth->>Storage : Validate Permissions
Storage-->>Auth : Permission Status
Auth->>Crypto : Sign Message
Crypto-->>Auth : MAC Signature
Auth-->>Client : Authenticated Request
Client->>Storage : Persist Configuration
Storage-->>Client : Confirmation
Diagram sources
Privilege Escalation Protection
The system implements multiple layers of protection:
- Permission Validation: Verifies user permissions before applying changes
- Parameter Sanitization: Validates all input parameters against security policies
- Atomic Operations: Ensures configuration changes are atomic or rolled back
- Audit Logging: Comprehensive logging of all configuration changes
Secure Configuration Storage
Configuration data is protected through:
- Encryption: All sensitive configuration data is encrypted at rest
- Integrity Checking: Cryptographic signatures verify data integrity
- Access Controls: Role-based access controls restrict configuration access
- Tamper Detection: Mechanisms detect and respond to tampering attempts
Section sources
Integration with Extensions Framework
The configuration system integrates seamlessly with the broader CTAP2 extensions framework:
Feature Advertisement
Configuration capabilities are advertised through the CTAP2 Info object:
| Option | Purpose | Security Impact |
|---|---|---|
| authnrCfg | Authenticator configuration support | Enables administrative functions |
| ep | Enterprise attestation capability | Supports organizational attestation |
| alwaysUv | User verification enforcement | Enhances authentication security |
| setMinPINLength | PIN length configuration | Controls authentication strength |
Extension Compatibility
The configuration system works with various extensions:
classDiagram
class ExtensionsFramework {
+register_extension(name, extension)
+advertise_capabilities()
+validate_compatibility()
}
class ConfigExtension {
+NAME "authnrCfg"
+is_supported(ctap) bool
+make_credential(options) processor
+get_assertion(options) processor
}
class MinPinLengthExtension {
+NAME "minPinLength"
+is_supported(ctap) bool
+make_credential(options) processor
}
ExtensionsFramework --> ConfigExtension : manages
ExtensionsFramework --> MinPinLengthExtension : manages
ConfigExtension --> MinPinLengthExtension : coordinates
Diagram sources
Section sources
Test Examples and Validation
The test suite demonstrates comprehensive validation of configuration functionality:
Enterprise Attestation Testing
Tests verify enterprise attestation functionality across different scenarios:
sequenceDiagram
participant Test as "Test Suite"
participant Config as "Config API"
participant Authenticator as "Authenticator"
participant Server as "WebAuthn Server"
Test->>Config : enable_enterprise_attestation()
Config->>Authenticator : Configure EP Mode
Authenticator-->>Config : Success Confirmation
Config-->>Test : Operation Complete
Test->>Server : Register with EP Attestation
Server->>Authenticator : Request Enterprise Certificate
Authenticator-->>Server : Enterprise Attestation
Server-->>Test : Validation Result
Diagram sources
PIN Length Configuration Tests
Comprehensive testing validates PIN length enforcement:
| Test Scenario | Validation Criteria | Expected Outcome |
|---|---|---|
| Minimum Length Setting | Length ≥ 4 characters | Success |
| Maximum Length Enforcement | Length ≤ 63 characters | Success |
| RP ID Restrictions | Valid RP ID list | Success |
| Force Change PIN | PIN change required | Success |
| Policy Violation | Short PIN attempt | PIN_POLICY_VIOLATION |
Credential Protection Testing
Tests validate credential protection policies:
flowchart TD
StartTest["Start Credential Protection Test"] --> CheckSupport{"Protection Supported?"}
CheckSupport --> |No| SkipTest["Skip Test"]
CheckSupport --> |Yes| SetPolicy["Configure Protection Policy"]
SetPolicy --> AttemptRegistration["Attempt Registration"]
AttemptRegistration --> ValidatePolicy["Validate Policy Application"]
ValidatePolicy --> TestAssertion["Test Credential Assertion"]
TestAssertion --> VerifySecurity["Verify Security Controls"]
VerifySecurity --> Cleanup["Cleanup Test State"]
Cleanup --> EndTest["End Test"]
SkipTest --> EndTest
Diagram sources
Section sources
Error Handling and Validation
The configuration system implements comprehensive error handling for various failure scenarios:
Error Classification
Configuration errors are categorized into distinct types:
| Error Type | Condition | Resolution |
|---|---|---|
| UNSUPPORTED_OPTION | Feature not supported | Check authenticator capabilities |
| PIN_REQUIRED | Missing authentication | Provide valid PIN/UV token |
| PIN_INVALID | Incorrect authentication | Verify credentials |
| PIN_POLICY_VIOLATION | Parameter violation | Adjust parameters according to policy |
| UNAUTHORIZED | Insufficient permissions | Obtain appropriate privileges |
Validation Pipeline
flowchart TD
ReceiveRequest["Receive Configuration Request"] --> ValidateFormat{"CBOR Format Valid?"}
ValidateFormat --> |No| FormatError["Return INVALID_CBOR"]
ValidateFormat --> |Yes| ValidateStructure{"Parameter Structure Valid?"}
ValidateStructure --> |No| StructureError["Return INVALID_PARAMETER"]
ValidateStructure --> |Yes| ValidatePermissions{"User Permissions Valid?"}
ValidatePermissions --> |No| PermissionError["Return UNAUTHORIZED"]
ValidatePermissions --> |Yes| ValidatePolicy{"Policy Compliance?"}
ValidatePolicy --> |No| PolicyError["Return PIN_POLICY_VIOLATION"]
ValidatePolicy --> |Yes| ExecuteChange["Execute Configuration Change"]
ExecuteChange --> Success["Return Success"]
FormatError --> End([Error Response])
StructureError --> End
PermissionError --> End
PolicyError --> End
Success --> End
Diagram sources
Unsupported Configuration Handling
The system gracefully handles unsupported configurations:
sequenceDiagram
participant Client as "Client Application"
participant Config as "Config Handler"
participant Info as "Info Object"
participant Authenticator as "Authenticator"
Client->>Config : Configuration Request
Config->>Info : Check Capability Support
Info-->>Config : Capability Status
Config->>Config : Validate Against Supported Features
alt Feature Not Supported
Config-->>Client : UNSUPPORTED_OPTION
else Feature Supported
Config->>Authenticator : Process Configuration
Authenticator-->>Config : Result
Config-->>Client : Response
end
Diagram sources
Section sources
Troubleshooting Guide
Common configuration issues and their resolutions:
Authentication Failures
Problem: Configuration commands fail with PIN-related errors Diagnosis: Check PIN/UV token validity and permissions Resolution: Verify token freshness and required permissions
Capability Issues
Problem: Configuration commands return UNSUPPORTED_OPTION Diagnosis: Verify authenticator capability advertisement Resolution: Check Info object for required options
Parameter Validation Errors
Problem: Configuration changes rejected with INVALID_PARAMETER Diagnosis: Review parameter format and constraints Resolution: Validate parameter structure against specification
State Synchronization Issues
Problem: Configuration changes not reflected in Info object Diagnosis: Verify persistence and notification mechanisms Resolution: Force Info refresh and verify storage integrity
Section sources
Conclusion
The Authenticator Configuration extension provides a robust, secure, and flexible framework for managing authenticator features. Through comprehensive CBOR encoding, multi-layered authentication, and strict validation mechanisms, it ensures safe and reliable configuration management. The integration with the Extensions framework enables seamless operation alongside other authenticator capabilities, while extensive testing validates functionality across diverse scenarios.
The implementation demonstrates best practices in security-conscious software development, with particular emphasis on privilege separation, parameter validation, and audit logging. Future enhancements may include additional configuration options, enhanced audit capabilities, and expanded integration with emerging WebAuthn features.