File size: 3,862 Bytes
28440fa | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 | # 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:
```bash
cd rust_signer
cargo build --release
```
### "Failed to lock memory"
Your system may have limits on locked memory. Increase the limit:
```bash
# 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
|