33 KiB
SecureBit.chat API Documentation
🏗️ Architecture Overview
SecureBit.chat is built as a client-side application with no backend servers. The "API" consists of JavaScript classes and methods that handle cryptography, P2P connections. Version 4.02.442 introduces complete ASN.1 validation for enhanced key security.
📋 Table of Contents
📚 Core Classes
🔐 EnhancedSecureCryptoUtils
Central cryptographic utilities class providing military-grade encryption with complete ASN.1 validation.
Key Generation
generateECDHKeyPair()
static async generateECDHKeyPair(): Promise<CryptoKeyPair>
Generates non-extractable ECDH P-384 key pair for secure key exchange.
Returns: CryptoKeyPair with P-384 keys
Throws: Error if key generation fails
Example:
const keyPair = await EnhancedSecureCryptoUtils.generateECDHKeyPair();
console.log(keyPair.privateKey.algorithm.namedCurve); // "P-384"
generateECDSAKeyPair()
static async generateECDSAKeyPair(): Promise<CryptoKeyPair>
Generates non-extractable ECDSA P-384 key pair for digital signatures.
Returns: CryptoKeyPair for signing and verification
Throws: Error if key generation fails
Encryption/Decryption
encryptMessage()
static async encryptMessage(
message: string,
encryptionKey: CryptoKey,
macKey: CryptoKey,
metadataKey: CryptoKey,
messageId: string,
sequenceNumber: number = 0
): Promise<EncryptedMessage>
Encrypts a message with metadata protection and sequence numbers.
Parameters:
- message - Plaintext message (max 2000 chars)
- encryptionKey - AES-GCM 256-bit key
- macKey - HMAC key for authentication
- metadataKey - Key for metadata encryption
- messageId - Unique message identifier
- sequenceNumber - Message sequence for replay protection
Returns:
```typescript
interface EncryptedMessage {
messageIv: number[];
messageData: number[];
metadataIv: number[];
metadataData: number[];
mac: number[];
version: string;
}
Example:
const encrypted = await EnhancedSecureCryptoUtils.encryptMessage(
"Hello, secure world!",
encryptionKey,
macKey,
metadataKey,
"msg_12345",
42
);
decryptMessage()
static async decryptMessage(
encryptedPayload: EncryptedMessage,
encryptionKey: CryptoKey,
macKey: CryptoKey,
metadataKey: CryptoKey,
expectedSequenceNumber?: number
): Promise<DecryptedMessage>
Decrypts and verifies an encrypted message.
Returns:
```typescript
interface DecryptedMessage {
message: string;
messageId: string;
timestamp: number;
sequenceNumber: number;
}
Key Exchange
deriveSharedKeys()
static async deriveSharedKeys(
privateKey: CryptoKey,
publicKey: CryptoKey,
🔒 ASN1Validator (NEW)
Complete ASN.1 DER parser and validation system for cryptographic key security.
Overview
The ASN1Validator class provides comprehensive structural validation of all cryptographic keys according to PKCS standards and RFC specifications.
Constructor
const asn1Validator = new ASN1Validator();
Methods
validateKeyStructure(keyData)
validateKeyStructure(keyData: ArrayBuffer): boolean
Complete structural validation of cryptographic keys using ASN.1 DER parsing.
Parameters:
- keyData: ArrayBuffer - Raw key data to validate
Returns:
- boolean - True if validation passes, false otherwise
Throws:
- Error - Detailed error message for validation failures
Example:
const isValid = asn1Validator.validateKeyStructure(keyData);
if (!isValid) {
console.error('Key structure validation failed');
}
parseDER(data)
parseDER(data: ArrayBuffer): ASN1Structure
Parses ASN.1 DER encoded data into structured format.
Parameters:
- data: ArrayBuffer - DER encoded data
Returns:
- ASN1Structure - Parsed ASN.1 structure
Example:
const parsed = asn1Validator.parseDER(keyData);
console.log('Parsed structure:', parsed);
validateSPKI(parsed)
validateSPKI(parsed: ASN1Structure): boolean
Validates SubjectPublicKeyInfo structure according to RFC 5280.
Parameters:
- parsed: ASN1Structure - Parsed ASN.1 structure
Returns:
- boolean - True if SPKI structure is valid
Example:
if (!asn1Validator.validateSPKI(parsed)) {
throw new Error('Invalid SPKI structure');
}
validateOID(parsed)
validateOID(parsed: ASN1Structure): string
Validates algorithm OID and returns supported curve name.
Parameters:
- parsed: ASN1Structure - Parsed ASN.1 structure
Returns:
- string - Supported curve name ('P-256' or 'P-384')
Throws:
- Error - If OID is not supported
Example:
try {
const curve = asn1Validator.validateOID(parsed);
console.log('Supported curve:', curve);
} catch (error) {
console.error('Unsupported curve:', error.message);
}
validateECPoint(parsed)
validateECPoint(parsed: ASN1Structure): boolean
Validates elliptic curve point format and structure.
Parameters:
- parsed: ASN1Structure - Parsed ASN.1 structure
Returns:
- boolean - True if EC point is valid
Throws:
- Error - If EC point format is invalid
Example:
if (!asn1Validator.validateECPoint(parsed)) {
throw new Error('Invalid EC point format');
}
Properties
supportedOIDs
readonly supportedOIDs: Record<string, string>
Supported algorithm OIDs and their corresponding curve names.
Example:
console.log(asn1Validator.supportedOIDs);
// Output: {
// '1.2.840.10045.3.1.7': 'P-256',
// '1.3.132.0.34': 'P-384'
// }
maxKeySize
readonly maxKeySize: number
Maximum allowed key size in bytes (2000).
Example:
console.log('Max key size:', asn1Validator.maxKeySize); // 2000
minKeySize
readonly minKeySize: number
Minimum allowed key size in bytes (50).
Example:
console.log('Min key size:', asn1Validator.minKeySize); // 50
Integration Examples
Enhanced Key Import
// Enhanced key import with ASN.1 validation
const importKey = async (keyData, keyType) => {
// Validate key structure before processing
if (!asn1Validator.validateKeyStructure(keyData)) {
throw new Error('Key structure validation failed');
}
// Proceed with standard key import
return await crypto.subtle.importKey(
keyType,
keyData,
algorithm,
extractable,
keyUsages
);
};
Enhanced Key Export
// Enhanced key export with validation
const exportKey = async (key, format) => {
const exported = await crypto.subtle.exportKey(format, key);
// Validate exported key structure
if (format === 'spki' && !asn1Validator.validateKeyStructure(exported)) {
throw new Error('Exported key validation failed');
}
return exported;
};
Real-time Validation
// Continuous validation during operations
const validateOperation = (operation, keyData) => {
// Validate key structure before each operation
if (!asn1Validator.validateKeyStructure(keyData)) {
throw new Error('Key validation failed during operation');
}
return operation(keyData);
};
Error Handling
Common Error Types
// OID validation errors
try {
asn1Validator.validateOID(parsed);
} catch (error) {
if (error.message.includes('Unsupported curve')) {
console.error('Algorithm not supported');
}
}
// EC point format errors
try {
asn1Validator.validateECPoint(parsed);
} catch (error) {
if (error.message.includes('Only uncompressed')) {
console.error('Compressed EC points not supported');
}
if (error.message.includes('Key size outside')) {
console.error('Key size limits exceeded');
}
}
// SPKI structure errors
try {
asn1Validator.validateSPKI(parsed);
} catch (error) {
if (error.message.includes('Invalid SPKI')) {
console.error('Key structure is invalid');
}
}
Performance Characteristics
Validation Timing
// Measure validation performance
const measureValidation = (keyData) => {
const start = performance.now();
const isValid = asn1Validator.validateKeyStructure(keyData);
const duration = performance.now() - start;
console.log(`Validation took ${duration.toFixed(2)}ms`);
console.log(`Validation result: ${isValid}`);
return { isValid, duration };
};
Batch Validation
// Validate multiple keys efficiently
const validateMultipleKeys = (keyArray) => {
const results = [];
const start = performance.now();
for (const keyData of keyArray) {
const result = asn1Validator.validateKeyStructure(keyData);
results.push({ keyData, isValid: result });
}
const totalTime = performance.now() - start;
const avgTime = totalTime / keyArray.length;
console.log(`Validated ${keyArray.length} keys in ${totalTime.toFixed(2)}ms`);
console.log(`Average time per key: ${avgTime.toFixed(2)}ms`);
return results;
};
Testing and Validation
Unit Test Examples
describe('ASN1Validator', () => {
let asn1Validator;
beforeEach(() => {
asn1Validator = new ASN1Validator();
});
test('validates correct P-384 key structure', () => {
const validKey = generateValidP384Key();
expect(asn1Validator.validateKeyStructure(validKey)).toBe(true);
});
test('rejects modified key with valid header', () => {
const modifiedKey = modifyKeyData(validKey);
expect(asn1Validator.validateKeyStructure(modifiedKey)).toBe(false);
});
test('rejects unsupported curve OID', () => {
const invalidOIDKey = generateKeyWithInvalidOID();
expect(() => asn1Validator.validateOID(invalidOIDKey)).toThrow();
});
test('rejects compressed EC point format', () => {
const compressedKey = generateCompressedKey();
expect(() => asn1Validator.validateECPoint(compressedKey)).toThrow();
});
});
Performance Test Examples
describe('ASN1Validator Performance', () => {
test('validation completes within 10ms', () => {
const start = performance.now();
asn1Validator.validateKeyStructure(validKey);
const duration = performance.now() - start;
expect(duration).toBeLessThan(10);
});
test('handles high-frequency validation', () => {
const iterations = 1000;
const start = performance.now();
for (let i = 0; i < iterations; i++) {
asn1Validator.validateKeyStructure(validKey);
}
const duration = performance.now() - start;
const avgTime = duration / iterations;
expect(avgTime).toBeLessThan(1); // < 1ms average
});
});
Migration Guide
From Version 4.01.x
// Old code (v4.01.x)
const importKey = async (keyData, keyType) => {
return await crypto.subtle.importKey(keyType, keyData, algorithm, extractable, keyUsages);
};
// New code (v4.02.x) - Enhanced with ASN.1 validation
const importKey = async (keyData, keyType) => {
// Add ASN.1 validation
if (!asn1Validator.validateKeyStructure(keyData)) {
throw new Error('Key structure validation failed');
}
return await crypto.subtle.importKey(keyType, keyData, algorithm, extractable, keyUsages);
};
Breaking Changes
- Enhanced key validation now performs complete ASN.1 parsing
- Stricter key acceptance criteria for improved security
- New error types for validation failures
- Performance impact minimal (< 10ms per validation)
Backward Compatibility
- Existing keys are validated on next use
- Valid key structures continue to work unchanged
- Fallback support from P-384 to P-256 maintained
- Error handling provides clear feedback for invalid keys
📚 Core Classes
🔐 EnhancedSecureCryptoUtils
Central cryptographic utilities class providing military-grade encryption.
Key Generation
generateECDHKeyPair()
``javascript static async generateECDHKeyPair(): Promise Generates non-extractable ECDH P-384 key pair for secure key exchange. Returns: CryptoKeyPair with P-384 keys Throws: Error if key generation fails Example: javascriptconst keyPair = await EnhancedSecureCryptoUtils.generateECDHKeyPair(); console.log(keyPair.privateKey.algorithm.namedCurve); // "P-384" generateECDSAKeyPair() javascriptstatic async generateECDSAKeyPair(): Promise Generates non-extractable ECDSA P-384 key pair for digital signatures. Returns: CryptoKeyPair for signing and verification Throws: Error if key generation fails Encryption/Decryption encryptMessage() javascriptstatic async encryptMessage( message: string, encryptionKey: CryptoKey, macKey: CryptoKey, metadataKey: CryptoKey, messageId: string, sequenceNumber: number = 0 ): Promise Encrypts a message with metadata protection and sequence numbers. Parameters:
message - Plaintext message (max 2000 chars) encryptionKey - AES-GCM 256-bit key macKey - HMAC key for authentication metadataKey - Key for metadata encryption messageId - Unique message identifier sequenceNumber - Message sequence for replay protection
Returns: typescriptinterface EncryptedMessage { messageIv: number[]; messageData: number[]; metadataIv: number[]; metadataData: number[]; mac: number[]; version: string; } Example: javascriptconst encrypted = await EnhancedSecureCryptoUtils.encryptMessage( "Hello, secure world!", encryptionKey, macKey, metadataKey, "msg_12345", 42 ); decryptMessage() javascriptstatic async decryptMessage( encryptedPayload: EncryptedMessage, encryptionKey: CryptoKey, macKey: CryptoKey, metadataKey: CryptoKey, expectedSequenceNumber?: number ): Promise Decrypts and verifies an encrypted message. Returns: typescriptinterface DecryptedMessage { message: string; messageId: string; timestamp: number; sequenceNumber: number; } Key Exchange deriveSharedKeys() javascriptstatic async deriveSharedKeys( privateKey: CryptoKey, publicKey: CryptoKey, salt: Uint8Array ): Promise Derives shared encryption keys using ECDH + HKDF. Parameters:
privateKey - Local ECDH private key publicKey - Remote ECDH public key salt - 64-byte cryptographic salt
Returns: typescriptinterface SharedKeys { encryptionKey: CryptoKey; macKey: CryptoKey; metadataKey: CryptoKey; fingerprint: string; timestamp: number; version: string; } Example: javascriptconst salt = EnhancedSecureCryptoUtils.generateSalt(); const sharedKeys = await EnhancedSecureCryptoUtils.deriveSharedKeys( localPrivateKey, remotePublicKey, salt ); console.log('Key fingerprint:', sharedKeys.fingerprint); Digital Signatures signData() javascriptstatic async signData( privateKey: CryptoKey, data: string | Uint8Array ): Promise<number[]> Signs data with ECDSA P-384. Parameters:
privateKey - ECDSA private key data - Data to sign
Returns: Signature as byte array Example: javascriptconst signature = await EnhancedSecureCryptoUtils.signData( ecdsaPrivateKey, "Important message" ); verifySignature() javascriptstatic async verifySignature( publicKey: CryptoKey, signature: number[], data: string | Uint8Array ): Promise Verifies ECDSA signature. Returns: true if signature is valid Authentication generateMutualAuthChallenge() javascriptstatic generateMutualAuthChallenge(): AuthChallenge Generates cryptographic challenge for mutual authentication. Returns: typescriptinterface AuthChallenge { challenge: number[]; timestamp: number; nonce: number[]; version: string; } createAuthProof() javascriptstatic async createAuthProof( challenge: AuthChallenge, privateKey: CryptoKey, publicKey: CryptoKey ): Promise Creates cryptographic proof for challenge response. Returns: typescriptinterface AuthProof { challenge: number[]; timestamp: number; nonce: number[]; responseTimestamp: number; publicKeyHash: string; signature: number[]; version: string; } verifyAuthProof() javascriptstatic async verifyAuthProof( proof: AuthProof, challenge: AuthChallenge, publicKey: CryptoKey ): Promise Verifies authentication proof against challenge. Utility Functions generateSalt() javascriptstatic generateSalt(): number[] Generates 64-byte cryptographically secure salt. sanitizeMessage() javascriptstatic sanitizeMessage(message: string): string Sanitizes user input to prevent XSS attacks. Example: javascriptconst clean = EnhancedSecureCryptoUtils.sanitizeMessage("<script>alert('xss')</script>Hello"); // Returns: "Hello" calculateSecurityLevel() javascriptstatic async calculateSecurityLevel(securityManager: any): Promise Calculates real-time security level based on active protections. Returns: typescriptinterface SecurityLevel { level: 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN'; score: number; // 0-100 color: 'green' | 'yellow' | 'red'; verificationResults: Record<string, VerificationResult>; timestamp: number; details: string; }
interface VerificationResult { passed: boolean; details: string; } generateVerificationCode() javascriptstatic generateVerificationCode(): string Generates 6-character verification code for out-of-band authentication. Returns: Code in format "AB-CD-EF" calculateKeyFingerprint() javascriptstatic async calculateKeyFingerprint(keyData: number[]): Promise Calculates SHA-256 fingerprint of key data for MITM protection. encryptData() / decryptData() javascriptstatic async encryptData(data: any, password: string): Promise static async decryptData(encryptedData: string, password: string): Promise High-level encryption/decryption for offer/answer exchange. Example: javascriptconst password = EnhancedSecureCryptoUtils.generateSecurePassword(); const encrypted = await EnhancedSecureCryptoUtils.encryptData( { message: "secret data" }, password ); const decrypted = await EnhancedSecureCryptoUtils.decryptData(encrypted, password); 🌐 EnhancedSecureWebRTCManager Manages P2P connections with enhanced security features. Constructor javascriptnew EnhancedSecureWebRTCManager( onMessage: (message: string, type: string) => void, onStatusChange: (status: string) => void, onKeyExchange: (fingerprint: string) => void, onVerificationRequired: (code: string) => void ) Parameters:
onMessage - Callback for received messages onStatusChange - Callback for connection state changes onKeyExchange - Callback when keys are exchanged onVerificationRequired - Callback when verification code is generated
Connection Management createSecureOffer() javascriptasync createSecureOffer(): Promise Creates encrypted connection offer with ECDH keys and authentication. Returns: typescriptinterface SecureOffer { type: 'enhanced_secure_offer'; sdp: string; ecdhPublicKey: SignedPublicKey; ecdsaPublicKey: SignedPublicKey; salt: number[]; verificationCode: string; authChallenge: AuthChallenge; sessionId: string; timestamp: number; version: string; securityLevel: SecurityLevel; }
interface SignedPublicKey { keyType: 'ECDH' | 'ECDSA'; keyData: number[]; timestamp: number; version: string; signature: number[]; } Example: javascriptconst webrtcManager = new EnhancedSecureWebRTCManager(/.../); const offer = await webrtcManager.createSecureOffer(); console.log('Verification code:', offer.verificationCode); createSecureAnswer() javascriptasync createSecureAnswer(offerData: SecureOffer): Promise Creates encrypted response to connection offer. Returns: typescriptinterface SecureAnswer { type: 'enhanced_secure_answer'; sdp: string; ecdhPublicKey: SignedPublicKey; ecdsaPublicKey: SignedPublicKey; authProof: AuthProof; timestamp: number; version: string; securityLevel: SecurityLevel; } handleSecureAnswer() javascriptasync handleSecureAnswer(answerData: SecureAnswer): Promise Processes encrypted answer and establishes connection. Throws: Error if answer is invalid or authentication fails Message Handling sendSecureMessage() javascriptasync sendSecureMessage(message: string): Promise Sends encrypted message through secure channel. Parameters:
message - Plaintext message (auto-sanitized)
Features:
Automatic encryption with metadata protection Sequence number tracking Rate limiting (60 messages/minute) Perfect Forward Secrecy key rotation
Example: javascriptawait webrtcManager.sendSecureMessage("Hello, secure world!"); Connection States typescripttype ConnectionState = | 'disconnected' // No connection | 'connecting' // Establishing connection | 'verifying' // Verifying security codes | 'connected' // Fully connected and verified | 'failed' // Connection failed | 'reconnecting' // Attempting to reconnect | 'peer_disconnected'; // Peer disconnected Security Features calculateSecurityLevel() javascriptasync calculateSecurityLevel(): Promise Real-time security assessment with verification of:
✅ Encryption functionality ✅ ECDH key exchange ✅ ECDSA signatures ✅ Mutual authentication ✅ Metadata protection ✅ Replay protection ✅ Non-extractable keys ✅ Rate limiting ✅ Perfect Forward Secrecy
shouldRotateKeys() javascriptshouldRotateKeys(): boolean Determines if PFS key rotation is needed (every 5 minutes or 100 messages). isConnected() javascriptisConnected(): boolean Returns true if WebRTC data channel is open and ready. getConnectionInfo() javascriptgetConnectionInfo(): ConnectionInfo Returns: typescriptinterface ConnectionInfo { fingerprint: string; isConnected: boolean; isVerified: boolean; connectionState: string; iceConnectionState: string; verificationCode: string; } Perfect Forward Secrecy rotateKeys() javascriptasync rotateKeys(): Promise Performs key rotation for Perfect Forward Secrecy. Returns: true if rotation successful getKeysForVersion() javascriptgetKeysForVersion(version: number): KeySet | null Retrieves keys for specific version (for decrypting old messages). Returns: typescriptinterface KeySet { encryptionKey: CryptoKey; macKey: CryptoKey; metadataKey: CryptoKey; } Connection Control disconnect() javascriptdisconnect(): void Cleanly disconnects and cleans up all resources. confirmVerification() javascriptconfirmVerification(): void Confirms that verification codes match (called after manual verification). 🧪 Testing Unit Testing Examples javascript// Test encryption/decryption round-trip async function testEncryptionRoundTrip() { const originalMessage = 'Test message for encryption'; const keys = await generateTestKeys();
const encrypted = await EnhancedSecureCryptoUtils.encryptMessage(
originalMessage,
keys.encryptionKey,
keys.macKey,
keys.metadataKey,
'test-id',
0
);
const decrypted = await EnhancedSecureCryptoUtils.decryptMessage(
encrypted,
keys.encryptionKey,
keys.macKey,
keys.metadataKey
);
assert.equal(decrypted.message, originalMessage);
assert.equal(decrypted.messageId, 'test-id');
assert.equal(decrypted.sequenceNumber, 0);
}
// Test key generation async function testKeyGeneration() { const ecdhPair = await EnhancedSecureCryptoUtils.generateECDHKeyPair(); const ecdsaPair = await EnhancedSecureCryptoUtils.generateECDSAKeyPair();
// Verify key properties
assert.equal(ecdhPair.privateKey.algorithm.name, 'ECDH');
assert.equal(ecdhPair.privateKey.algorithm.namedCurve, 'P-384');
assert.equal(ecdhPair.privateKey.extractable, false);
assert.equal(ecdsaPair.privateKey.algorithm.name, 'ECDSA');
assert.equal(ecdsaPair.privateKey.algorithm.namedCurve, 'P-384');
assert.equal(ecdsaPair.privateKey.extractable, false);
}
// Test signature verification async function testSignatureVerification() { const keyPair = await EnhancedSecureCryptoUtils.generateECDSAKeyPair(); const data = 'Test data to sign';
const signature = await EnhancedSecureCryptoUtils.signData(
keyPair.privateKey,
data
);
const isValid = await EnhancedSecureCryptoUtils.verifySignature(
keyPair.publicKey,
signature,
data
);
assert.equal(isValid, true);
// Test with wrong data
const invalidVerification = await EnhancedSecureCryptoUtils.verifySignature(
keyPair.publicKey,
signature,
'Wrong data'
);
assert.equal(invalidVerification, false);
}
// Helper function for tests async function generateTestKeys() { const ecdhPair = await EnhancedSecureCryptoUtils.generateECDHKeyPair(); const salt = EnhancedSecureCryptoUtils.generateSalt();
// For testing, we'll create a mock "remote" key pair
const remotePair = await EnhancedSecureCryptoUtils.generateECDHKeyPair();
const sharedKeys = await EnhancedSecureCryptoUtils.deriveSharedKeys(
ecdhPair.privateKey,
remotePair.publicKey,
salt
);
return sharedKeys;
} Integration Testing javascript// Test full P2P connection flow async function testP2PConnection() { let manager1Messages = []; let manager2Messages = [];
const manager1 = new EnhancedSecureWebRTCManager(
(msg, type) => manager1Messages.push({msg, type}),
(status) => console.log('Manager1 status:', status),
(fingerprint) => console.log('Manager1 fingerprint:', fingerprint),
(code) => console.log('Manager1 verification:', code)
);
const manager2 = new EnhancedSecureWebRTCManager(
(msg, type) => manager2Messages.push({msg, type}),
(status) => console.log('Manager2 status:', status),
(fingerprint) => console.log('Manager2 fingerprint:', fingerprint),
(code) => console.log('Manager2 verification:', code)
);
// Create offer
const offer = await manager1.createSecureOffer();
// Create answer
const answer = await manager2.createSecureAnswer(offer);
// Handle answer
await manager1.handleSecureAnswer(answer);
// Wait for connection
await waitForConnection(manager1, manager2);
// Verify both are connected
assert.equal(manager1.isConnected(), true);
assert.equal(manager2.isConnected(), true);
// Test message exchange
await manager1.sendSecureMessage('Hello from manager1');
await manager2.sendSecureMessage('Hello from manager2');
// Wait for messages to arrive
await new Promise(resolve => setTimeout(resolve, 1000));
// Verify messages were received
assert.equal(manager2Messages.length > 0, true);
assert.equal(manager1Messages.length > 0, true);
}
async function waitForConnection(manager1, manager2, timeout = 10000) { const start = Date.now();
while (Date.now() - start < timeout) {
if (manager1.isConnected() && manager2.isConnected()) {
return;
}
await new Promise(resolve => setTimeout(resolve, 100));
}
throw new Error('Connection timeout');
}
🔒 Security Framework APIs
🔐 SecureKeyManager
Manages cryptographic keys with WeakMap-based isolation and secure access methods.
_initializeSecureKeyStorage()
_initializeSecureKeyStorage(): void
Initializes secure key storage with WeakMap isolation.
Example:
javascriptconst keyManager = new SecureKeyManager();
keyManager._initializeSecureKeyStorage();
_getSecureKey(keyName)
_getSecureKey(keyName: string): CryptoKey | ArrayBuffer | Uint8Array
Retrieves a key from secure storage with access tracking.
Parameters:
- keyName - Name of the key to retrieve
Returns: The stored key value
Throws: Error if key not found
Example:
javascriptconst encryptionKey = keyManager._getSecureKey('encryptionKey');
_setSecureKey(keyName, keyValue, options)
_setSecureKey(
keyName: string,
keyValue: CryptoKey | ArrayBuffer | Uint8Array,
options?: { validate?: boolean }
): void
Stores a key in secure storage with validation.
Parameters:
- keyName - Name for the key
- keyValue - The key to store
- options.validate - Whether to validate the key value
Example:
javascriptkeyManager._setSecureKey('encryptionKey', newKey, { validate: true });
_validateKeyValue(keyValue, keyName)
_validateKeyValue(keyValue: any, keyName: string): void
Validates key value for security requirements.
Throws: Error if validation fails
_rotateKeys()
_rotateKeys(): void
Performs secure key rotation with new key generation.
_emergencyKeyWipe()
_emergencyKeyWipe(): void
Immediately removes all keys from memory for threat response.
🔒 ConnectionMutexManager
Manages connection operations with mutex-based race condition protection.
_withMutex(mutexName, operation, timeout)
_withMutex(
mutexName: string,
operation: () => Promise<any>,
timeout?: number
): Promise<any>
Executes an operation with mutex protection.
Parameters:
- mutexName - Name of the mutex lock
- operation - Async function to execute
- timeout - Timeout in milliseconds (default: 15000)
Returns: Result of the operation
Throws: Error if mutex is locked or operation fails
Example:
javascriptawait mutexManager._withMutex('connectionOperation', async () => {
await this._generateEncryptionKeys();
await this._establishSecureChannel();
});
_generateOperationId()
_generateOperationId(): string
Generates unique operation identifier for tracking.
Returns: Unique operation ID string
_cleanupFailedOfferCreation(operationId)
_cleanupFailedOfferCreation(operationId: string): Promise<void>
Performs cleanup for failed connection operations.
Parameters:
- operationId - ID of the failed operation
🛡️ SecureLogger
Provides environment-aware logging with data sanitization.
_secureLog(level, message, data)
_secureLog(
level: 'debug' | 'info' | 'warn' | 'error',
message: string,
data?: any
): void
Logs message with data sanitization and environment detection.
Parameters:
- level - Log level
- message - Log message
- data - Optional data object (will be sanitized)
Example:
javascriptlogger._secureLog('debug', 'Connection established', {
userId: 'user123',
encryptionKey: new Uint8Array(32)
});
// Production: No output
// Development: [SecureBit:DEBUG] Connection established { userId: 'user123', encryptionKey: '[REDACTED]' }
debug(message, data)
debug(message: string, data?: any): void
Logs debug message (development only).
info(message, data)
info(message: string, data?: any): void
Logs info message.
warn(message, data)
warn(message: string, data?: any): void
Logs warning message.
error(message, data)
error(message: string, data?: any): void
Logs error message.
🔐 Backward Compatibility
Getters and Setters
// Secure key access with backward compatibility
get encryptionKey(): CryptoKey {
return this._getSecureKey('encryptionKey');
}
set encryptionKey(value: CryptoKey) {
this._setSecureKey('encryptionKey', value, { validate: true });
}
get macKey(): CryptoKey {
return this._getSecureKey('macKey');
}
set macKey(value: CryptoKey) {
this._setSecureKey('macKey', value, { validate: true });
}
🔒 Security Framework Usage Examples
Complete Security Setup
// Initialize security framework
const keyManager = new SecureKeyManager();
const mutexManager = new ConnectionMutexManager();
const logger = new SecureLogger();
// Secure connection establishment
await mutexManager._withMutex('connectionOperation', async () => {
logger.debug('Starting secure connection');
// Generate and store keys securely
const keyPair = await EnhancedSecureCryptoUtils.generateECDHKeyPair();
keyManager._setSecureKey('privateKey', keyPair.privateKey, { validate: true });
// Establish connection
await this._establishSecureChannel();
logger.info('Secure connection established');
});
Emergency Security Response
// Emergency key wipe in case of security threat
keyManager._emergencyKeyWipe();
logger.warn('Emergency key wipe completed');
// Force cleanup
if (typeof gc === 'function') {
gc();
}