Configuration Security - FeitianTech/postquantum-webauthn-platform GitHub Wiki

Configuration Security

Table of Contents

  1. Introduction
  2. Secret Key Management
  3. Environment-Based Configuration
  4. Feature Flags and Security Settings
  5. HTTPS Enforcement and Cookie Security
  6. Metadata Service Trust Anchor Configuration
  7. Container Security Configuration
  8. Production Deployment Security
  9. Configuration Validation and Auditing
  10. Common Misconfigurations and Best Practices

Introduction

The Post-Quantum WebAuthn Platform implements comprehensive security configuration practices designed to protect against various attack vectors while maintaining operational flexibility. This document covers the secure management of sensitive configuration values, HTTPS enforcement mechanisms, cookie security configurations, and container deployment security settings.

The platform follows security-by-design principles with multiple layers of protection including encrypted session storage, certificate pinning for metadata services, and strict container isolation. All sensitive configuration values are managed through environment variables with fallback mechanisms for development environments.

Secret Key Management

Secure Generation and Storage

The platform implements a sophisticated secret key resolution mechanism that prioritizes security through multiple configuration methods:

flowchart TD
Start([Secret Key Resolution]) --> EnvCheck{Environment Variable<br/>FIDO_SERVER_SECRET_KEY<br/>Available?}
EnvCheck --> |Yes| DecodeEnv[Decode UTF-8 String]
EnvCheck --> |No| FileCheck{Secret Key File<br/>FIDO_SERVER_SECRET_KEY_FILE<br/>Available?}
FileCheck --> |Yes| ReadFile[Read Binary File]
FileCheck --> |No| DefaultPath[Check Default Path<br/>app.instance_path/session-secret.key]
DefaultPath --> DefaultExists{Default Key<br/>Exists?}
DefaultExists --> |Yes| UseDefault[Use Existing Key]
DefaultExists --> |No| GenerateNew[Generate New 32-byte<br/>Random Key]
GenerateNew --> StoreTemp[Store Temporarily<br/>with Atomic Operations]
StoreTemp --> FinalCheck{Final Key<br/>Available?}
FinalCheck --> |Yes| Success[Return Secret Key]
FinalCheck --> |No| UseGenerated[Use Generated Key]
UseGenerated --> Success
DecodeEnv --> Success
ReadFile --> Success
UseDefault --> Success
Loading

Diagram sources

  • server/server/config.py

Configuration Methods

The secret key resolution follows a priority order:

  1. Environment Variable Method: FIDO_SERVER_SECRET_KEY - Direct string input
  2. File-Based Method: FIDO_SERVER_SECRET_KEY_FILE - Binary file containing the key
  3. Default Storage: Automatic generation and persistent storage in the application instance path

Security Implementation Details

The secret key generation process incorporates several security measures:

  • Cryptographic Randomness: Uses os.urandom(32) for 256-bit entropy
  • Atomic File Operations: Implements os.replace() for atomic key storage
  • Secure Permissions: Creates keys with restricted file permissions during generation
  • Temporary File Cleanup: Ensures temporary files are securely removed

Section sources

  • server/server/config.py

Environment-Based Configuration

Sensitive Configuration Variables

The platform exposes several environment variables for security-critical configuration:

Variable Purpose Security Impact Production Recommendation
FIDO_SERVER_SECRET_KEY Session encryption key High - Must be cryptographically strong Use environment variable, not hardcoded
FIDO_SERVER_SECRET_KEY_FILE Path to binary key file High - File system security matters Use absolute paths, restrict file permissions
FIDO_SERVER_RP_NAME Relying Party display name Medium - User experience impact Configure appropriately for environment
FIDO_SERVER_RP_ID Relying Party identifier High - Authentication security Must match actual domain
FIDO_SERVER_TRUSTED_ATTESTATION_CA_SUBJECTS Trusted CA subject names Critical - Attestation validation Restrict to known CAs only
FIDO_SERVER_TRUSTED_ATTESTATION_CA_FINGERPRINTS CA certificate fingerprints Critical - Certificate validation Use SHA-256 fingerprints

Environment Flag Parsing

The platform implements robust environment flag parsing with case-insensitive normalization:

flowchart TD
Input[Environment Variable] --> Normalize[Normalize to Lowercase<br/>Strip Whitespace]
Normalize --> CheckEmpty{Empty or<br/>Whitespace Only?}
CheckEmpty --> |Yes| ReturnNone[Return None]
CheckEmpty --> |No| CheckFalse{Contains<br/>False Values?}
CheckFalse --> |Yes| ReturnFalse[Return False]
CheckFalse --> |No| ReturnTrue[Return True]
FalseValues["'', '0', 'false', 'off', 'no'"]
CheckFalse --> |Contains| FalseValues
Loading

Diagram sources

  • server/server/config.py

Configuration Validation Patterns

The platform implements comprehensive validation for trust anchor configurations:

  • Subject Name Validation: Comma/newline-separated lists with whitespace trimming
  • Fingerprint Validation: Hexadecimal string filtering with minimum 40-character requirement
  • Certificate Format Verification: Base64 decoding with error handling

Section sources

  • server/server/config.py

Feature Flags and Security Settings

FIDO2 Feature Management

The platform utilizes the fido2.features module for managing feature flags with security implications:

classDiagram
class _Feature {
-_enabled : Optional[bool]
-_name : str
-_desc : str
+enabled : bool
+enabled.setter(value : bool)
+require(state : bool)
+warn()
}
class FeatureNotEnabledError {
<<Exception>>
}
class webauthn_json_mapping {
+enabled : bool
}
_Feature --> FeatureNotEnabledError : raises
webauthn_json_mapping --|> _Feature
Loading

Diagram sources

  • fido2/features.py

Recommended Production Settings

For production deployments, the following feature flag configurations are recommended:

  1. WebAuthn JSON Mapping: Enable for JSON-friendly data representation
  2. Security Validation: Disable deprecated features to prevent security regressions
  3. Compatibility Mode: Maintain backward compatibility where necessary

Feature Flag Security Implications

Feature Security Impact Production Status Recommendation
webauthn_json_mapping Data format compatibility Stable Enable for modern clients
Deprecated Features Security regression risk Legacy Disable in production

Section sources

  • fido2/features.py

HTTPS Enforcement and Cookie Security

Cookie Configuration Strategy

The platform implements secure cookie configuration with dynamic security attributes based on connection context:

sequenceDiagram
participant Request as HTTP Request
participant Handler as Route Handler
participant Cookie as Cookie Manager
participant Response as HTTP Response
Request->>Handler : Process Request
Handler->>Cookie : Check Request Context
Cookie->>Cookie : Determine Secure Context
alt Secure Connection (HTTPS)
Cookie->>Response : Set HttpOnly, Secure, SameSite=None
else Insecure Connection (HTTP)
Cookie->>Response : Set HttpOnly, SameSite=Lax
end
Response-->>Request : Secure Cookie Applied
Loading

Diagram sources

  • server/server/metadata.py

Dynamic Security Attribute Configuration

The cookie security configuration adapts to the connection context:

  • Secure Flag: Enabled for HTTPS connections, disabled for HTTP
  • SameSite Policy: None for secure connections, Lax for insecure connections
  • HttpOnly Flag: Always enabled for session cookies
  • Path Scope: Root path (/) for global accessibility

Metadata Session Cookie Implementation

The platform implements specialized session metadata cookies with enhanced security:

flowchart TD
SessionReq[Session Metadata Request] --> ContextCheck{Has Request<br/>Context?}
ContextCheck --> |No| ReturnNone[Return None]
ContextCheck --> |Yes| ParseCookie[Parse Cookie Value]
ParseCookie --> ValidateFormat[Validate Identifier Format]
ValidateFormat --> FormatValid{Valid Format?}
FormatValid --> |No| ReturnNone
FormatValid --> |Yes| CheckSecure[Check Secure Context]
CheckSecure --> SetAttributes[Set Cookie Attributes]
SetAttributes --> ApplyCookie[Apply to Response]
Loading

Diagram sources

  • server/server/metadata.py

Cookie Security Parameters

Parameter Secure Value Insecure Value Security Benefit
secure True False Prevents transmission over HTTP
httponly True Not applicable Prevents JavaScript access
samesite None Lax Controls cross-site request behavior
max_age Configurable Not applicable Limits cookie lifetime

Section sources

  • server/server/metadata.py

Metadata Service Trust Anchor Configuration

Certificate Pinning Implementation

The platform implements certificate pinning for the FIDO Metadata Service (MDS) using multiple trust anchors:

graph TB
subgraph "Trust Anchors"
RootCert[GlobalSign Root CA<br/>SHA-256: 246...9F]
Additional1[ISRG Root X1<br/>SHA-256: 293...9C]
Additional2[DigiCert Global Root G2<br/>SHA-256: 310...4E]
Additional3[Baltimore CyberTrust Root<br/>SHA-256: 326...55]
end
subgraph "Metadata Service"
MDSEndpoint[https://mds3.fidoalliance.org/]
end
RootCert --> MDSEndpoint
Additional1 --> MDSEndpoint
Additional2 --> MDSEndpoint
Additional3 --> MDSEndpoint
Loading

Diagram sources

  • server/server/config.py

Trust Root Configuration

The platform embeds multiple root certificates for redundancy and security:

  1. GlobalSign Root CA: Primary trust anchor for FIDO Alliance certificates
  2. ISRG Root X1: Additional intermediate authority
  3. DigiCert Global Root G2: Enterprise-grade certificate authority
  4. Baltimore CyberTrust Root: Legacy certificate authority support

Certificate Validation Process

sequenceDiagram
participant Client as WebAuthn Client
participant Validator as Certificate Validator
participant TrustStore as Trust Store
participant MDS as Metadata Service
Client->>Validator : Request Metadata
Validator->>MDS : HTTPS Request
MDS->>Validator : Certificate Chain
Validator->>TrustStore : Verify Chain
TrustStore->>Validator : Validation Result
alt Certificate Valid
Validator->>Client : Return Metadata
else Certificate Invalid
Validator->>Client : Reject Connection
end
Loading

Diagram sources

  • server/server/config.py

Certificate Pinning Security Benefits

  • Prevents MITM Attacks: Validates certificate chain against embedded roots
  • Reduces Attack Surface: Limits trust to known authorities only
  • Enhances Resilience: Multiple trust anchors provide redundancy
  • Compliance Support: Meets security standards requiring certificate pinning

Section sources

  • server/server/config.py

Container Security Configuration

Multi-Stage Docker Build Security

The platform implements a secure multi-stage Docker build process:

graph TB
subgraph "Build Stage (python-builder)"
BaseImage1[python:3.12-slim]
BuildTools[Install Build Tools<br/>build-essential, cmake, git]
LibOQS[Copy Prebuilt liboqs]
Dependencies[Install Python Dependencies]
Cleanup1[Remove Build Dependencies]
end
subgraph "Runtime Stage (runtime)"
BaseImage2[python:3.12-slim]
RuntimeLibs[Minimal Runtime Libraries<br/>libssl3]
LibOQS2[Copy liboqs Runtime]
AppFiles[Copy Application Code]
Cleanup2[Clean Package Cache]
end
subgraph "Security Hardening"
NonRoot[Non-Root User Execution]
MinimalImage[Minimal Attack Surface]
ReadOnlyFS[Read-Only Filesystem]
end
BaseImage1 --> BuildTools
BuildTools --> LibOQS
LibOQS --> Dependencies
Dependencies --> Cleanup1
Cleanup1 --> BaseImage2
BaseImage2 --> RuntimeLibs
RuntimeLibs --> LibOQS2
LibOQS2 --> AppFiles
AppFiles --> Cleanup2
Cleanup2 --> NonRoot
NonRoot --> MinimalImage
MinimalImage --> ReadOnlyFS
Loading

Diagram sources

  • Dockerfile

Security Configuration Elements

The Dockerfile implements several security hardening measures:

  1. Minimal Base Image: Uses python:3.12-slim for reduced attack surface
  2. Build-Time Isolation: Separates build dependencies from runtime
  3. Library Path Configuration: Sets appropriate library loading paths
  4. Environment Variables: Configures security-related environment settings
  5. Command Execution: Uses Gunicorn with proper process management

Runtime Security Settings

Security Aspect Implementation Security Benefit
User Privileges Non-root execution Limits privilege escalation
Filesystem Access Read-only root filesystem Prevents unauthorized modifications
Network Exposure Controlled port binding Limits network attack surface
Process Isolation Gunicorn WSGI server Provides process separation

Container Deployment Configuration

The render.yaml configuration specifies secure deployment parameters:

  • Service Type: Web application with Docker runtime
  • Deployment Plan: Free tier with automatic deployment
  • Docker Context: Root directory with Dockerfile
  • Auto-deployment: Enabled for continuous delivery

Section sources

  • Dockerfile
  • render.yaml

Production Deployment Security

Startup Security Validation

The platform implements comprehensive startup validation to ensure security prerequisites are met:

flowchart TD
Start[Server Startup] --> MetadataBootstrap[Bootstrap Metadata Service]
MetadataBootstrap --> CloudStorage{Cloud Storage<br/>Enabled?}
CloudStorage --> |Yes| ValidateGCS[Validate GCS Credentials]
CloudStorage --> |No| SkipGCS[Skip Validation]
ValidateGCS --> StorageReady{Storage Ready?}
StorageReady --> |Yes| TestSessions[Test Session Storage]
StorageReady --> |No| FailStartup[Startup Failure]
TestSessions --> TestCredentials[Test Credential Storage]
TestCredentials --> CleanupTest[Cleanup Test Session]
CleanupTest --> Success[Startup Complete]
SkipGCS --> TestSessions
FailStartup --> Shutdown[Graceful Shutdown]
Loading

Diagram sources

  • server/server/startup.py

Production Security Checklist

For production deployments, the following security configurations must be implemented:

  1. Secret Key Management: Use environment variables for secret keys
  2. HTTPS Enforcement: Deploy with SSL/TLS certificates
  3. Certificate Pinning: Verify metadata service certificates
  4. Container Security: Run containers with minimal privileges
  5. Network Security: Configure firewall rules and network policies
  6. Monitoring: Implement security event logging and alerting

Environment-Specific Configuration

Environment Secret Key Method HTTPS Requirement Debug Mode Logging Level
Development Default generation Optional Enabled DEBUG
Staging Environment variables Required Disabled INFO
Production Environment variables Required Disabled WARNING

Section sources

  • server/server/startup.py

Configuration Validation and Auditing

Configuration Validation Framework

The platform implements multiple layers of configuration validation:

graph TB
subgraph "Input Validation"
EnvVars[Environment Variables]
FilePaths[File Paths]
Certificates[Certificate Data]
end
subgraph "Validation Logic"
FormatCheck[Format Validation]
LengthCheck[Length Constraints]
ContentCheck[Content Verification]
PermissionCheck[Permission Validation]
end
subgraph "Output Validation"
Success[Valid Configuration]
Warning[Configuration Warnings]
Error[Configuration Errors]
end
EnvVars --> FormatCheck
FilePaths --> LengthCheck
Certificates --> ContentCheck
FormatCheck --> Success
LengthCheck --> Warning
ContentCheck --> Error
PermissionCheck --> Error
Loading

Audit Trail Implementation

The platform maintains comprehensive audit trails for security-critical operations:

  1. Configuration Changes: Logs all environment variable modifications
  2. Secret Key Generation: Tracks key generation events
  3. Certificate Validation: Records certificate verification results
  4. Metadata Updates: Monitors metadata service interactions

Security Monitoring Indicators

Event Type Log Level Security Impact Monitoring Action
Secret Key Change INFO High Alert on unexpected changes
Certificate Validation Failure ERROR Critical Immediate investigation
Metadata Download Failure WARNING Medium Investigate connectivity issues
Cookie Security Violation ERROR High Block request immediately

Section sources

  • server/server/config.py
  • server/server/routes/general.py

Common Misconfigurations and Best Practices

Frequently Encountered Security Issues

  1. Hardcoded Secrets: Never commit secret keys to version control
  2. Insecure File Permissions: Ensure secret files have restricted access
  3. Missing HTTPS: Always deploy with SSL/TLS in production
  4. Weak Certificate Validation: Implement proper certificate pinning
  5. Debug Mode in Production: Disable debug mode in production environments

Secure Configuration Patterns

Environment Variable Management

# Recommended: Use environment variables for secrets
export FIDO_SERVER_SECRET_KEY=$(openssl rand -hex 32)
export FIDO_SERVER_SECRET_KEY_FILE="/path/to/secure/key/file"
export FIDO_SERVER_RP_ID="your-domain.com"
export FIDO_SERVER_RP_NAME="Production WebAuthn Service"

Container Security Configuration

# Use non-root user
USER 1000

# Set security-related environment variables
ENV PYTHONPATH=/app:${PYTHONPATH}
ENV LD_LIBRARY_PATH=/opt/liboqs/lib:/usr/local/lib

# Bind to non-privileged port
EXPOSE 8000

Production Deployment Checklist

  • Secret keys configured via environment variables
  • HTTPS certificates installed and validated
  • Certificate pinning enabled for metadata services
  • Container privileges restricted to minimum necessary
  • Network access limited to essential ports only
  • Logging configured for security events
  • Monitoring and alerting systems deployed
  • Backup and disaster recovery procedures established

Configuration Testing Procedures

  1. Secret Key Validation: Verify key generation and persistence
  2. Certificate Verification: Test certificate pinning functionality
  3. HTTPS Enforcement: Confirm secure connection requirements
  4. Cookie Security: Validate cookie attribute configuration
  5. Metadata Service Access: Test trust anchor validation
  6. Container Security: Verify privilege restrictions and isolation

Incident Response Configuration

In the event of a security incident, the platform provides several mechanisms for rapid response:

  • Immediate Logging: All security events are logged with timestamps
  • Alert Integration: Can integrate with monitoring systems
  • Configuration Rollback: Ability to revert to known-good configurations
  • Access Control: Granular permission controls for administrative access

Section sources

  • server/server/config.py
  • Dockerfile
⚠️ **GitHub.com Fallback** ⚠️