mev-beta/docs/planning/03_HIGH-001_Private_Key_Security_Plan.md

HIGH-001: Private Key Memory Security - Detailed Fix Plan

Issue ID: HIGH-001
Category: Security
Priority: High
Status: Not Started
Generated: October 9, 2025
Estimate: 2-3 hours

Overview

This plan addresses private key memory security vulnerabilities by enhancing the key clearing mechanism and implementing secure memory handling practices. The goal is to ensure that private key material is properly cleared from memory after use and protected during operations to prevent memory-based attacks.

Current Implementation Issues

• Inadequate clearing of private key material in pkg/security/keymanager.go
• Lack of secure memory zeroing for big.Int private key data
• Insufficient memory protection during key operations
• Missing verification for memory clearing operations

Implementation Tasks

1. Enhance clearPrivateKey() Function

Task ID: HIGH-001.1
Time Estimate: 1 hour
Dependencies: None

Enhance the clearPrivateKey() function in pkg/security/keymanager.go:

• Implement secure memory zeroing for all private key data
• Use platform-agnostic memory clearing approach
• Ensure all related data structures are properly cleared
• Add verification methods to confirm clearing worked

// Enhanced clearPrivateKey function
func (km *KeyManager) clearPrivateKey(key *ecdsa.PrivateKey) error {
    if key == nil {
        return nil
    }
    
    // Clear D parameter (private key scalar)
    if key.D != nil {
        km.secureClearBigInt(key.D)
    }
    
    // Clear PublicKey components
    if key.X != nil {
        km.secureClearBigInt(key.X)
    }
    if key.Y != nil {
        km.secureClearBigInt(key.Y)
    }
    
    // Clear other fields if needed
    key.D = nil
    key.X = nil
    key.Y = nil
    
    return nil
}

2. Implement Secure Memory Zeroing for big.Int

Task ID: HIGH-001.2
Time Estimate: 1 hour
Dependencies: HIGH-001.1

Create secure clearing for big.Int objects:

• Implement function to overwrite big.Int underlying bytes
• Use constant-time operations to prevent timing attacks
• Handle all possible big.Int representations
• Add proper error handling and verification

// Secure clearing for big.Int
func (km *KeyManager) secureClearBigInt(bi *big.Int) {
    if bi == nil {
        return
    }
    
    // Get the bytes representation
    bytes := bi.Bytes()
    
    // Clear the underlying memory
    for i := range bytes {
        bytes[i] = 0
    }
    
    // Set bits to zero
    bi.SetInt64(0)
    bi.SetBytes([]byte{})
}

3. Add Memory Protection for Key Operations

Task ID: HIGH-001.3
Time Estimate: 0.5 hours
Dependencies: HIGH-001.1, HIGH-001.2

Implement memory protection during key operations:

• Secure temporary variables during key operations
• Clear intermediate calculation results
• Protect against memory dumps during sensitive operations
• Use memory locking where appropriate

4. Create Unit Tests for Memory Clearing Verification

Task ID: HIGH-001.4
Time Estimate: 0.5 hours
Dependencies: HIGH-001.1, HIGH-001.2, HIGH-001.3

Develop comprehensive tests for memory clearing:

• Verify that private key data is actually cleared
• Test clearing of different key sizes
• Validate that cleared data cannot be retrieved
• Test concurrent key clearing operations

func TestClearPrivateKey(t *testing.T) {
    // Generate test key
    key, err := ecdsa.GenerateKey(crypto.S256(), rand.Reader)
    require.NoError(t, err)
    
    // Store original value for verification
    originalD := new(big.Int).Set(key.D)
    
    // Clear the key
    km := &KeyManager{}
    err = km.clearPrivateKey(key)
    require.NoError(t, err)
    
    // Verify that the key is effectively cleared
    assert.True(t, key.D.Sign() == 0 || key.D.Cmp(big.NewInt(0)) == 0)
}

5. Add Memory Usage Monitoring for Key Operations

Task ID: HIGH-001.5
Time Estimate: 0.25 hours
Dependencies: HIGH-001.1, HIGH-001.2, HIGH-001.3

Implement monitoring for key-related memory operations:

• Track memory allocation during key operations
• Monitor for potential memory leaks
• Log memory operations for audit purposes
• Alert on unusual memory usage patterns

Implementation Details

Memory Clearing Best Practices

• Use constant-time operations to prevent timing attacks
• Overwrite memory with non-sensitive data before releasing
• Clear all copies of sensitive data
• Consider using mlock and munlock on Unix systems for memory locking

Secure Implementation Example

import (
    "crypto/rand"
    "math/big"
    "runtime"
    "unsafe"
)

// Additional secure clearing functions
func (km *KeyManager) secureClearBytes(data []byte) {
    for i := range data {
        data[i] = 0
    }
    runtime.KeepAlive(data) // Ensure data isn't garbage collected early
}

func (km *KeyManager) secureClearBytesPtr(data *[]byte) {
    if data != nil {
        km.secureClearBytes(*data)
        *data = nil
    }
}

Testing Strategy

• Unit tests for all clearing functions
• Memory dump analysis to verify clearing effectiveness
• Performance testing to ensure no significant impact
• Concurrency testing for thread safety

Code Review Checklist

• All sensitive data is properly cleared
• Constant-time operations are used where needed
• Error handling is implemented for clearing operations
• Unit tests verify clearing effectiveness
• Memory usage monitoring is implemented
• No timing side-channel vulnerabilities are introduced

Rollback Strategy

If issues arise after deployment:

1. Revert to previous key clearing implementation
2. Temporarily disable enhanced clearing if causing issues
3. Monitor system stability and performance

Success Metrics

• Successful clearing of private key data
• No remaining private key material in memory after clearing
• All unit tests pass for clearing operations
• No performance degradation beyond acceptable limits
• No memory leaks detected