-
Notifications
You must be signed in to change notification settings - Fork 0
WebAuthn Specific Errors
- Introduction
- CTAP2 Error System
- Client Error System
- Specialized Exceptions
- Error Propagation Mechanisms
- Error Translation and User Messages
- Error Handling Patterns
- Testing and Validation
- Best Practices
The Post-Quantum WebAuthn Platform implements a comprehensive error handling system specifically designed for WebAuthn and CTAP2 protocols. This system provides structured error reporting, automatic error translation, and user-friendly error messages across the entire authentication pipeline. The error handling framework consists of multiple specialized error classes that inherit from Python's built-in Exception class, each targeting specific failure scenarios in the WebAuthn authentication process.
The platform's error handling system operates on multiple levels:
- CTAP2 Status Codes: Native CTAP2 protocol error codes (0x00-0xFF)
- Client Error Classification: High-level client-side error categorization
- Specialized Exceptions: Device-specific and operation-specific error types
- User-Facing Translation: Automatic conversion to human-readable error messages
The CtapError.ERR enum defines all CTAP2 status codes according to the FIDO2 specification, covering a comprehensive range of authentication and communication failures.
classDiagram
class CtapError {
+ERR code
+UNKNOWN_ERR unknown_code
+__init__(code : int)
+__str__() str
}
class ERR {
+SUCCESS : 0x00
+INVALID_COMMAND : 0x01
+INVALID_PARAMETER : 0x02
+TIMEOUT : 0x05
+CHANNEL_BUSY : 0x06
+NOT_ALLOWED : 0x30
+PIN_INVALID : 0x31
+REQUEST_TOO_LARGE : 0x39
+ACTION_TIMEOUT : 0x3A
+OTHER : 0x7F
+__str__() str
}
class UNKNOWN_ERR {
+value : int
+name : "UNKNOWN_ERR"
+__str__() str
+__repr__() str
}
CtapError --> ERR : contains
CtapError --> UNKNOWN_ERR : fallback_for_unknown_codes
Diagram sources
- fido2/ctap.py
The CTAP2 error system includes several critical status codes:
| Code | Constant | Description | Impact |
|---|---|---|---|
| 0x00 | SUCCESS | Operation completed successfully | Normal completion |
| 0x01 | INVALID_COMMAND | Command not supported or invalid | Protocol violation |
| 0x02 | INVALID_PARAMETER | Parameter out of range or missing | Configuration error |
| 0x05 | TIMEOUT | Operation timed out | Network/device latency |
| 0x06 | CHANNEL_BUSY | Channel currently processing another request | Resource contention |
| 0x30 | NOT_ALLOWED | Operation not allowed in current state | Permission issue |
| 0x39 | REQUEST_TOO_LARGE | Request exceeds maximum size | Size limitation |
| 0x3A | ACTION_TIMEOUT | User action timeout exceeded | User interaction failure |
The CTAP2 error system organizes status codes into logical categories:
flowchart TD
A[CTAP2 Error] --> B[Success Codes]
A --> C[Command Errors]
A --> D[Parameter Errors]
A --> E[Timeout Errors]
A --> F[Permission Errors]
A --> G[Resource Errors]
A --> H[Extension Errors]
A --> I[Vendor Errors]
B --> B1[0x00: SUCCESS]
C --> C1[0x01: INVALID_COMMAND]
C --> C2[0x04: INVALID_SEQ]
D --> D1[0x02: INVALID_PARAMETER]
D --> D2[0x14: MISSING_PARAMETER]
D --> D3[0x2C: INVALID_OPTION]
E --> E1[0x05: TIMEOUT]
E --> E2[0x2F: USER_ACTION_TIMEOUT]
E --> E3[0x3A: ACTION_TIMEOUT]
F --> F1[0x30: NOT_ALLOWED]
F --> F2[0x27: OPERATION_DENIED]
F --> F3[0x40: UNAUTHORIZED_PERMISSION]
G --> G1[0x18: LARGE_BLOB_STORAGE_FULL]
G --> G2[0x28: KEY_STORE_FULL]
G --> G3[0x32: PIN_BLOCKED]
H --> H1[0xE0-0xEF: EXTENSION_FIRST-LAST]
I --> I1[0xF0-0xFF: VENDOR_FIRST-LAST]
Section sources
- fido2/ctap.py
The ClientError.ERR enum provides high-level classification of client-side errors, enabling consistent error handling across different authentication scenarios.
classDiagram
class ClientError {
+ERR code
+cause : Any
+__init__(code, cause)
+__repr__() str
}
class ERR {
+OTHER_ERROR : 1
+BAD_REQUEST : 2
+CONFIGURATION_UNSUPPORTED : 3
+DEVICE_INELIGIBLE : 4
+TIMEOUT : 5
+__call__(cause) ClientError
}
ClientError --> ERR : contains
Diagram sources
- fido2/client/init.py
The client error system categorizes errors into five primary types:
| Code | Constant | Description | Common Scenarios |
|---|---|---|---|
| 1 | OTHER_ERROR | Generic unclassified error | Unexpected failures |
| 2 | BAD_REQUEST | Invalid request parameters | Malformed requests |
| 3 | CONFIGURATION_UNSUPPORTED | Unsupported configuration | Device limitations |
| 4 | DEVICE_INELIGIBLE | Device cannot fulfill request | Compatibility issues |
| 5 | TIMEOUT | Operation exceeded time limits | Network/device delays |
The platform implements sophisticated error translation logic that maps CTAP2 errors to client errors:
flowchart TD
A[CTAP2 Error] --> B{Error Classification}
B --> C[DEVICE_INELIGIBLE]
B --> D[TIMEOUT]
B --> E[CONFIGURATION_UNSUPPORTED]
B --> F[BAD_REQUEST]
B --> G[OTHER_ERROR]
C --> C1[CREDENTIAL_EXCLUDED]
C --> C2[NO_CREDENTIALS]
D --> D1[KEEPALIVE_CANCEL]
D --> D2[ACTION_TIMEOUT]
D --> D3[USER_ACTION_TIMEOUT]
E --> E1[UNSUPPORTED_ALGORITHM]
E --> E2[UNSUPPORTED_OPTION]
E --> E3[KEY_STORE_FULL]
F --> F1[INVALID_COMMAND]
F --> F2[INVALID_PARAMETER]
F --> F3[PIN_INVALID]
F --> F4[PIN_BLOCKED]
F --> F5[REQUEST_TOO_LARGE]
Section sources
- fido2/client/init.py
The ApduError exception handles APDU (Application Protocol Data Unit) communication failures specific to U2F devices.
classDiagram
class ApduError {
+code : int
+data : bytes
+__init__(code : int, data : bytes)
+__repr__() str
}
class APDU {
+OK : 0x9000
+USE_NOT_SATISFIED : 0x6985
+WRONG_DATA : 0x6A80
}
ApduError --> APDU : uses_codes
Diagram sources
- fido2/ctap1.py
The CaptureError exception manages fingerprint capture failures during biometric enrollment and authentication.
classDiagram
class CaptureError {
+code : int
+__init__(code : int)
+__str__() str
}
class FPBioEnrollment {
+FEEDBACK feedback_codes
+capture() bytes
+cancel() void
}
class FEEDBACK {
+FP_GOOD : 0x00
+FP_TOO_HIGH : 0x01
+FP_TOO_LOW : 0x02
+FP_POOR_QUALITY : 0x07
+FP_MERGE_FAILURE : 0x0A
+NO_USER_ACTIVITY : 0x0D
}
CaptureError --> FEEDBACK : maps_to
FPBioEnrollment --> CaptureError : raises
Diagram sources
- fido2/ctap2/bio.py
All specialized exceptions inherit from Python's base Exception class:
classDiagram
class Exception {
<<built-in>>
}
class CtapError {
+ERR code
+__init__(code : int)
}
class ClientError {
+ERR code
+cause : Any
+__init__(code, cause)
}
class ApduError {
+code : int
+data : bytes
+__init__(code : int, data : bytes)
}
class CaptureError {
+code : int
+__init__(code : int)
}
Exception <|-- CtapError
Exception <|-- ClientError
Exception <|-- ApduError
Exception <|-- CaptureError
Section sources
- fido2/ctap.py
- fido2/client/init.py
- fido2/ctap1.py
- fido2/ctap2/bio.py
Errors flow from authenticators through multiple layers of the system:
sequenceDiagram
participant Client as WebAuthn Client
participant Backend as Client Backend
participant Device as Authenticator Device
participant System as System Layer
Client->>Backend : Authentication Request
Backend->>Device : CTAP Command
Device-->>Backend : CTAP Error Response
Backend->>Backend : Translate Error
Backend-->>Client : ClientError
Client->>System : Log/Error Report
System-->>Client : User-Facing Message
The error transformation process follows a standardized pipeline:
flowchart LR
A[Raw Authenticator Error] --> B[CTAP2 Error Handler]
B --> C[Error Classification]
C --> D[Client Error Translation]
D --> E[User-Facing Message]
B --> F[Unknown Error Handler]
F --> G[Generic Error Creation]
G --> E
Different device types implement specialized error handling:
| Device Type | Error Handler | Special Features |
|---|---|---|
| HID Devices | CtapDevice | USB/HID protocol errors |
| PCSC Readers | CtapPcscDevice | Smart card APDU errors |
| U2F Tokens | Ctap1 | Legacy U2F protocol |
| Biometric Devices | FPBioEnrollment | Fingerprint capture feedback |
Section sources
- fido2/pcsc.py
- fido2/client/init.py
The system automatically generates user-friendly error messages based on error codes:
flowchart TD
A[Error Code] --> B{Error Type}
B --> C[CTAP2 Error]
B --> D[Client Error]
B --> E[Device Error]
C --> C1["CTAP error: 0x01 - INVALID_COMMAND"]
D --> D1["Client error: 2 - BAD_REQUEST"]
E --> E1["Fingerprint capture error: 0x07"]
C1 --> F[User Interface Display]
D1 --> F
E1 --> F
Error messages preserve contextual information for debugging:
# Example error message construction
error_message = f"CTAP error: {self.code} (cause: {self.cause})"The error system supports localization through string formatting:
| Locale | Error Message Format | Example |
|---|---|---|
| en-US | "CTAP error: {code} - {description}" | "CTAP error: 0x01 - INVALID_COMMAND" |
| de-DE | "CTAP Fehler: {code} - {description}" | "CTAP Fehler: 0x01 - INVALID_COMMAND" |
| ja-JP | "{description}エラー: {code}" | "INVALID_COMMANDエラー: 0x01" |
Section sources
- fido2/ctap.py
- fido2/client/init.py
Common error handling patterns used throughout the codebase:
flowchart TD
A[Operation Attempt] --> B{Try Block}
B --> C[Execute Operation]
C --> D{Success?}
D --> |Yes| E[Return Result]
D --> |No| F[Catch Exception]
F --> G{Exception Type}
G --> H[CTAP Error]
G --> I[Client Error]
G --> J[Device Error]
H --> K[Translate to Client Error]
I --> L[Log and Report]
J --> M[Device-Specific Handling]
K --> N[User-Facing Message]
L --> N
M --> N
The system implements multiple error recovery strategies:
| Strategy | Use Case | Implementation |
|---|---|---|
| Retry | Temporary failures | Exponential backoff |
| Fallback | Alternative methods | Secondary authenticators |
| Graceful Degradation | Partial functionality | Reduced feature set |
| User Intervention | Manual resolution | User prompts |
Error handling includes comprehensive logging:
flowchart LR
A[Error Occurs] --> B[Log Error Details]
B --> C[Generate Error ID]
C --> D[Store in Error Log]
D --> E[Send to Monitoring]
E --> F[Alert if Necessary]
Section sources
- fido2/client/init.py
The platform includes comprehensive testing for error conditions:
flowchart TD
A[Test Suite] --> B[Unit Tests]
A --> C[Integration Tests]
A --> D[End-to-End Tests]
B --> B1[Individual Error Classes]
B --> B2[Error Translation Logic]
C --> C1[Device Communication Errors]
C --> C2[Network Failure Scenarios]
D --> D1[Complete Authentication Flow]
D --> D2[Error Recovery Paths]
| Test Category | Coverage | Examples |
|---|---|---|
| CTAP2 Errors | 95% | All status codes tested |
| Client Errors | 90% | All error translations validated |
| Device Errors | 85% | U2F, Biometric, PCSC tested |
| Edge Cases | 80% | Boundary conditions validated |
The testing framework supports simulated error conditions:
# Example test pattern for error simulation
def test_error_translation():
ctap_error = CtapError(ERR.INVALID_COMMAND)
client_error = _ctap2client_err(ctap_error)
assert client_error.code == ClientError.ERR.BAD_REQUESTSection sources
- tests/test_ctap2.py
- Specific Error Types: Use the most specific error type available
- Context Preservation: Always include error context when possible
- User-Friendly Messages: Translate technical errors to user-understandable messages
- Logging: Log all errors with sufficient context for debugging
- Recovery: Implement appropriate recovery strategies for transient errors
- Error Caching: Cache frequently occurring error patterns
- Lazy Loading: Load error message resources on demand
- Minimal Overhead: Keep error handling overhead minimal
- Async Processing: Handle errors asynchronously when possible
- Information Disclosure: Avoid exposing sensitive information in error messages
- Timing Attacks: Ensure error timing is consistent to prevent timing attacks
- Audit Logging: Log security-relevant errors for audit trails
- Rate Limiting: Implement rate limiting for error-generating operations
- Error Code Management: Maintain comprehensive error code documentation
- Translation Updates: Keep user-facing messages synchronized with code changes
- Monitoring Integration: Integrate error monitoring with operational dashboards
- Documentation Updates: Update error handling documentation regularly
The Post-Quantum WebAuthn Platform's error handling system provides a robust foundation for reliable WebAuthn authentication, ensuring that users receive meaningful feedback while maintaining security and performance standards.