documentation/INTEGRATION_GUIDE.md

Integration Guide: Adding Secure Signing to Coldstar SOL

This guide shows how to integrate the Rust secure signer into your existing Python Coldstar SOL CLI.

Overview

The Rust signing core will replace Python-based key handling with secure, memory-locked operations. The integration is designed to be minimally invasive to your existing codebase.

Integration Strategy

Before (Insecure):
┌─────────────────────────────────────────┐
│  Python CLI                              │
│  ├─ Load key from file                  │
│  ├─ Key in Python memory (INSECURE)     │
│  └─ Sign transaction in Python          │
└─────────────────────────────────────────┘

After (Secure):
┌─────────────────────────────────────────┐
│  Python CLI                              │
│  ├─ Load encrypted container            │
│  └─ Call Rust signer ──────────┐        │
└─────────────────────────────────┼────────┘
                                  ▼
                    ┌─────────────────────────┐
                    │  Rust Signing Core      │
                    │  ├─ Decrypt in locked   │
                    │  │   memory              │
                    │  ├─ Sign transaction    │
                    │  └─ Zeroize & return    │
                    └─────────────────────────┘

Security Checklist

After integration, verify:

• Plaintext keys are deleted (or securely backed up offline)
• Encrypted containers are created with strong passphrases (12+ characters)
• Passphrase prompts use getpass (not visible on screen)
• No plaintext keys are logged or printed
• File permissions on encrypted containers are restrictive (chmod 600)
• Backup encrypted containers securely
• Test signing with correct and incorrect passphrases

Rollback Plan

If you need to rollback to the old system:

1. Keep your original keypair.json backed up (securely!)
2. Keep the old wallet/transaction code in a separate branch
3. Test thoroughly before deleting plaintext keys

Performance Considerations

• FFI mode: ~0.1ms overhead per signature (negligible)
• CLI mode: ~10-50ms overhead per signature (process startup)

For production with high throughput, use FFI mode. For development or occasional use, CLI mode is fine.

Troubleshooting

"Secure signer not available"

The Rust library isn't built or not found. Build it:

cd rust_signer
cargo build --release

"Failed to lock memory"

Your system may have limits on locked memory. Increase the limit:

# Temporary (current session)
ulimit -l unlimited

# Permanent (add to /etc/security/limits.conf)
* soft memlock unlimited
* hard memlock unlimited

"Decryption failed"

• Check that you're using the correct passphrase
• Verify the encrypted container file isn't corrupted
• Try recreating the container from the original key

Next Steps

1. Integrate with UI: Add passphrase prompts to your UI
2. Key Rotation: Implement periodic key rotation
3. Multi-Sig: Extend for multi-signature support
4. Hardware Integration: Consider HSM integration for production

Support

For issues or questions:

• Check the README.md and SECURITY.md
• Review the example code in python_signer_example.py
• Open an issue with detailed logs and steps to reproduce