Skip to content

SSZcreate/Pentab_server / .agents/skills/cybersecurity/skills/implementing-hardware-security-key-authentication

implementing-hardware-security-key-authentication

Verified

Builds a FIDO2/WebAuthn relying party server with the python-fido2 library, covering registration and authentication ceremonies, YubiKey enrollment, resident key (discoverable credential/passkey) workflows, and user verification policies. Use when implementing phishing-resistant MFA with hardware security keys, building a WebAuthn relying party, enrolling YubiKeys for a workforce, or migrating password-based authentication to passkeys.

FileKindSize
LICENSEother11.0 KB
SKILL.mdskill md17.5 KB
references/api-reference.mdmarkdown6.3 KB
scripts/agent.pyscript37.9 KB

references/api-reference.md

View on GitHub
# API Reference: FIDO2/WebAuthn Hardware Security Key Authentication Server

## Overview

Implements a complete WebAuthn relying party server with registration/authentication ceremonies, YubiKey enrollment, credential management, recovery codes, and audit logging. Built on python-fido2 and Flask, supporting both roaming authenticators (USB/NFC security keys) and platform authenticators (Windows Hello, Touch ID).

## Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| fido2 | >=2.0.0 | Yubico's python-fido2 library for WebAuthn relying party operations |
| flask | >=2.3 | HTTP server framework for API endpoints and session management |
| cryptography | >=41.0 | Cryptographic primitives used by python-fido2 |

Install with: `pip install fido2 flask cryptography`

## CLI Usage

```bash
# Development server on localhost (no TLS needed)
python agent.py --rp-id localhost --rp-name "My App" --port 5000

# Production with strict security settings
python agent.py --rp-id auth.example.com --rp-name "Example Corp" \
    --user-verification required --attestation direct --db prod_keys.db

# Verbose logging for debugging
python agent.py --rp-id localhost --rp-name "Test" -v
```

## Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `--rp-id` | No | Relying Party ID -- must match the application domain (default: localhost) |
| `--rp-name` | No | Relying Party display name shown in authenticator prompts (default: FIDO2 Demo) |
| `--host` | No | Server bind address (default: localhost) |
| `--port` | No | Server port (default: 5000) |
| `--db` | No | SQLite database path for credentials and users (default: webauthn.db) |
| `--attestation` | No | Attestation preference: none, indirect, direct, enterprise (default: none) |
| `--user-verification` | No | UV requirement: required, preferred, discouraged (default: preferred) |
| `-v, --verbose` | No | Enable debug logging |

## API Endpoints

### Registration

#### `POST /api/register/begin`
Start the WebAuthn registration ceremony.

**Request body:**
```json
{
  "username": "alice",
  "display_name": "Alice Smith",
  "resident_key": true
}
```

**Response:** PublicKeyCredentialCreationOptions (JSON-serialized)

#### `POST /api/register/complete`
Complete registration with the authenticator's response.

**Request body:** Serialized PublicKeyCredential from `navigator.credentials.create()`

**Response:**
```json
{
  "status": "OK",
  "recovery_codes": ["A1B2C3D4", "E5F6G7H8", ...],
  "message": "Save these recovery codes securely."
}
```

### Authentication

#### `POST /api/authenticate/begin`
Start the WebAuthn authentication ceremony.

**Request body:**
```json
{
  "username": "alice"
}
```
Omit `username` for discoverable credential (passwordless) flow.

**Response:** PublicKeyCredentialRequestOptions (JSON-serialized)

#### `POST /api/authenticate/complete`
Complete authentication with the authenticator's assertion.

**Request body:** Serialized PublicKeyCredential from `navigator.credentials.get()`

**Response:**
```json
{
  "status": "OK",
  "username": "alice"
}
```

### Key Management

#### `GET /api/keys`
List all registered security keys for the authenticated user.

#### `POST /api/keys/<id>/revoke`
Revoke a security key. Requires at least one remaining active credential.

#### `PUT /api/keys/<id>/label`
Update a key's display label.

### Recovery

#### `POST /api/recover`
Authenticate using a recovery code when all keys are unavailable.

**Request body:**
```json
{
  "username": "alice",
  "recovery_code": "A1B2C3D4"
}
```

### Admin

#### `GET /api/admin/stats`
Deployment statistics: total users, credentials, backup key adoption, authentication metrics.

#### `GET /api/admin/audit-log?limit=100`
Authentication event audit trail with timestamps, usernames, event types, and IP addresses.

## Key Functions

### User Management

#### `create_user(conn, username, display_name)`
Creates a user with a cryptographically random 32-byte user handle.

#### `get_user_by_username(conn, username)` / `get_user_by_handle(conn, user_handle)`
User lookups by username (standard flow) or user handle (discoverable credential flow).

### Credential Management

#### `store_credential(conn, user_id, credential_id, public_key, sign_count, ...)`
Persists a WebAuthn credential with AAGUID, label, transport hints, and discoverable flag.

#### `get_user_credentials(conn, user_id)`
Retrieves all active (non-revoked) credentials for a user.

#### `revoke_credential(conn, credential_db_id, user_id)`
Soft-revokes a credential. Prevents revocation of the last remaining credential.

#### `update_sign_count(conn, credential_id, new_count)`
Updates sign count and last-used timestamp after successful authentication. Sign count regression is logged as a security event (possible cloned key).

### Recovery

#### `generate_recovery_codes(conn, user_id, count=8)`
Generates 8 one-time recovery codes (stored as SHA-256 hashes). Previous codes are invalidated.

#### `verify_recovery_code(conn, user_id, code)`
Verifies and consumes a recovery code (single-use).

### Helpers

#### `build_credential_descriptors(creds)`
Converts stored credentials to `PublicKeyCredentialDescriptor` list for WebAuthn ceremonies.

#### `reconstruct_credential_data(creds)`
Rebuilds `AttestedCredentialData` objects from database records for python-fido2 verification.

## Database Schema

| Table | Purpose |
|-------|---------|
| `users` | User accounts with random user handles, usernames, and passkey-only flag |
| `credentials` | WebAuthn credentials with public keys, sign counts, AAGUIDs, and revocation status |
| `auth_events` | Audit log of all registration, authentication, revocation, and recovery events |
| `recovery_codes` | Hashed one-time recovery codes with usage tracking |

## Security Features

| Feature | Implementation |
|---------|---------------|
| Phishing resistance | Origin binding via WebAuthn RP ID verification |
| Clone detection | Sign count validation with regression warnings |
| Recovery codes | SHA-256 hashed, single-use, auto-invalidated on regeneration |
| Session security | Secure, HttpOnly, SameSite=Strict cookies |
| Key revocation | Soft delete with minimum-one-key enforcement |
| Audit trail | All auth events logged with IP, user agent, and timestamp |
| Attestation verification | Configurable attestation preference for enterprise key verification |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall