272 lines
8.2 KiB
Markdown
272 lines
8.2 KiB
Markdown
# 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
|
|
```typescript
|
|
const keyPair = await crypto.generateKeyPair();
|
|
// Returns CryptoKeyPair with public and private keys
|
|
```
|
|
|
|
#### Public Key Export/Import
|
|
```typescript
|
|
const publicKeyBase64 = await crypto.exportPublicKey(keyPair.publicKey);
|
|
const importedKey = await crypto.importPublicKey(publicKeyBase64);
|
|
```
|
|
|
|
#### Data Signing and Verification
|
|
```typescript
|
|
const signature = await crypto.signData(privateKey, data);
|
|
const isValid = await crypto.verifySignature(publicKey, signature, data);
|
|
```
|
|
|
|
#### Challenge-Response Authentication
|
|
```typescript
|
|
// 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
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
- [x] Browser support detection
|
|
- [x] Secure context validation
|
|
- [x] Key pair generation
|
|
- [x] Public key export/import
|
|
- [x] Data signing and verification
|
|
- [x] User registration
|
|
- [x] User login
|
|
- [x] 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:
|
|
```typescript
|
|
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](https://www.w3.org/TR/WebCryptoAPI/)
|
|
- [ECDSA Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm)
|
|
- [P-256 Curve](https://en.wikipedia.org/wiki/NIST_Curve_P-256)
|
|
- [Challenge-Response Authentication](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication) |