canvas-website/docs/WEBCRYPTO_AUTH.md

WebCryptoAPI Authentication Implementation

This document describes the complete WebCryptoAPI authentication system implemented in this project.

Overview

The WebCryptoAPI authentication system provides cryptographic authentication using ECDSA P-256 key pairs, challenge-response authentication, and secure key storage. It integrates with the existing ODD (Open Data Directory) framework while providing a fallback authentication mechanism.

Architecture

Core Components

1. Crypto Module (src/lib/auth/crypto.ts)

   • WebCryptoAPI wrapper functions
   • Key pair generation (ECDSA P-256)
   • Public key export/import
   • Data signing and verification
   • User credential storage

2. CryptoAuthService (src/lib/auth/cryptoAuthService.ts)

   • High-level authentication service
   • Challenge-response authentication
   • User registration and login
   • Credential verification

3. Enhanced AuthService (src/lib/auth/authService.ts)

   • Integrates crypto authentication with ODD
   • Fallback mechanisms
   • Session management

4. UI Components

   • CryptoLogin.tsx - Cryptographic authentication UI
   • CryptoTest.tsx - Test component for verification

Features

✅ Implemented

• ECDSA P-256 Key Pairs: Secure cryptographic key generation
• Challenge-Response Authentication: Prevents replay attacks
• Public Key Infrastructure: Store and verify public keys
• Browser Support Detection: Checks for WebCryptoAPI availability
• Secure Context Validation: Ensures HTTPS requirement
• Fallback Authentication: Works with existing ODD system
• Modern UI: Responsive design with dark mode support
• Comprehensive Testing: Test component for verification

🔧 Technical Details

Key Generation

const keyPair = await crypto.generateKeyPair();
// Returns CryptoKeyPair with public and private keys

Public Key Export/Import

const publicKeyBase64 = await crypto.exportPublicKey(keyPair.publicKey);
const importedKey = await crypto.importPublicKey(publicKeyBase64);

Data Signing and Verification

const signature = await crypto.signData(privateKey, data);
const isValid = await crypto.verifySignature(publicKey, signature, data);

Challenge-Response Authentication

// Generate challenge
const challenge = `${username}:${timestamp}:${random}`;

// Sign challenge during registration
const signature = await crypto.signData(privateKey, challenge);

// Verify during login
const isValid = await crypto.verifySignature(publicKey, signature, challenge);

Browser Requirements

Minimum Requirements

• WebCryptoAPI Support: window.crypto.subtle
• Secure Context: HTTPS or localhost
• Modern Browser: Chrome 37+, Firefox 34+, Safari 11+, Edge 12+

Feature Detection

const hasWebCrypto = typeof window.crypto !== 'undefined' && 
                    typeof window.crypto.subtle !== 'undefined';
const isSecure = window.isSecureContext;

Security Considerations

✅ Implemented Security Measures

1. Secure Context Requirement: Only works over HTTPS
2. ECDSA P-256: Industry-standard elliptic curve
3. Challenge-Response: Prevents replay attacks
4. Key Storage: Public keys stored securely
5. Input Validation: Username format validation
6. Error Handling: Comprehensive error management

⚠️ Security Notes

1. Private Key Storage: Currently simplified for demo purposes

   • In production, use Web Crypto API's key storage
   • Consider hardware security modules (HSM)
   • Implement proper key derivation

2. Session Management:

   • Integrates with existing ODD session system
   • Consider implementing JWT tokens
   • Add session expiration

3. Network Security:

   • All crypto operations happen client-side
   • No private keys transmitted over network
   • Consider adding server-side verification

Usage

Basic Authentication Flow

import { CryptoAuthService } from './lib/auth/cryptoAuthService';

// Register a new user
const registerResult = await CryptoAuthService.register('username');
if (registerResult.success) {
  console.log('User registered successfully');
}

// Login with existing user
const loginResult = await CryptoAuthService.login('username');
if (loginResult.success) {
  console.log('User authenticated successfully');
}

Integration with React Context

import { useAuth } from './context/AuthContext';

const { login, register } = useAuth();

// The AuthService automatically tries crypto auth first,
// then falls back to ODD authentication
const success = await login('username');

Testing the Implementation

import CryptoTest from './components/auth/CryptoTest';

// Render the test component to verify functionality
<CryptoTest />

File Structure

src/
├── lib/
│   ├── auth/
│   │   ├── crypto.ts              # WebCryptoAPI wrapper
│   │   ├── cryptoAuthService.ts   # High-level auth service
│   │   ├── authService.ts         # Enhanced auth service
│   │   └── account.ts             # User account management
│   └── utils/
│       └── browser.ts             # Browser support detection
├── components/
│   └── auth/
│       ├── CryptoLogin.tsx        # Crypto auth UI
│       └── CryptoTest.tsx         # Test component
└── css/
    └── crypto-auth.css            # Styles for crypto components

Dependencies

Required Packages

• one-webcrypto: WebCryptoAPI polyfill (^1.0.3)
• @oddjs/odd: Open Data Directory framework (^0.37.2)

Browser APIs Used

• window.crypto.subtle: WebCryptoAPI
• window.localStorage: Key storage
• window.isSecureContext: Security context check

Testing

Manual Testing

1. Navigate to the application
2. Use the CryptoTest component to run automated tests
3. Verify all test cases pass
4. Test on different browsers and devices

Test Cases

• Browser support detection
• Secure context validation
• Key pair generation
• Public key export/import
• Data signing and verification
• User registration
• User login
• Credential verification

Troubleshooting

Common Issues

1. "Browser not supported"

   • Ensure you're using a modern browser
   • Check if WebCryptoAPI is available
   • Verify HTTPS or localhost

2. "Secure context required"

   • Access the application over HTTPS
   • For development, use localhost

3. "Key generation failed"

   • Check browser console for errors
   • Verify WebCryptoAPI permissions
   • Try refreshing the page

4. "Authentication failed"

   • Verify user exists
   • Check stored credentials
   • Clear browser data and retry

Debug Mode

Enable debug logging by setting:

localStorage.setItem('debug_crypto', 'true');

Future Enhancements

Planned Improvements

1. Enhanced Key Storage: Use Web Crypto API's key storage
2. Server-Side Verification: Add server-side signature verification
3. Multi-Factor Authentication: Add additional authentication factors
4. Key Rotation: Implement automatic key rotation
5. Hardware Security: Support for hardware security modules

Advanced Features

1. Zero-Knowledge Proofs: Implement ZKP for enhanced privacy
2. Threshold Cryptography: Distributed key management
3. Post-Quantum Cryptography: Prepare for quantum threats
4. Biometric Integration: Add biometric authentication

Contributing

When contributing to the WebCryptoAPI authentication system:

1. Security First: All changes must maintain security standards
2. Test Thoroughly: Run the test suite before submitting
3. Document Changes: Update this documentation
4. Browser Compatibility: Test on multiple browsers
5. Performance: Ensure crypto operations don't block UI

References

• WebCryptoAPI Specification
• ECDSA Algorithm
• P-256 Curve
• Challenge-Response Authentication