A neural cryptography library implementing adversarial training for secure communication. NeuroSync features three neural networks (Alice, Bob, and Eve) that learn to encrypt and decrypt messages while an adversary attempts to break the encryption, resulting in continuously improving security.
NeuroSync is inspired by Google Brain's research on neural cryptography, where neural networks learn to protect communications. The system consists of:
- Alice (Encoder): Transforms plaintext into ciphertext using a shared key
- Bob (Decoder): Recovers plaintext from ciphertext using the same key
- Eve (Adversary): Attempts to decrypt without the key, driving security improvements
Through adversarial training, Alice and Bob learn encryption schemes that Eve cannot break, while the system provides dynamic key rotation, error correction, and a complete protocol stack for real-world applications. You can test it out in the demo notebook to see how it works!
- Adversarial Training: Three-network system that continuously improves encryption security
- Dynamic Key Rotation: Automatic key updates with encrypted key exchange
- Error Correction: Parity-based error detection and correction for reliable transmission
- Complete Protocol Stack: Packet-based communication with checksums, sequencing, and reassembly
- GPU Acceleration: Full CUDA support for fast training and inference
- Simple API: High-level interface for easy integration
- Python 3.9 or higher
- PyTorch 2.8.0 or higher
- CUDA-capable GPU (recommended for training)
pip install NeuroSyncgit clone https://github.com/CooDiiNgg/NeuroSync.git
cd NeuroSync
pip install -e .git clone https://github.com/CooDiiNgg/NeuroSync.git
cd NeuroSync
pip install -e ".[dev]"NeuroSync automatically detects and uses CUDA when available. For CPU-only installation:
pip install NeuroSync
# PyTorch will use CPU if no CUDA is availableFor specific CUDA versions, install PyTorch first following the official instructions, then install NeuroSync.
from NeuroSync import NeuroSync
# Load from pretrained weights
cipher = NeuroSync.from_pretrained("./weights/")
# Encrypt a message
encrypted = cipher.encrypt("Hello, World!")
# Decrypt it back
decrypted = cipher.decrypt(encrypted)
print(decrypted) # "Hello, World!"from NeuroSync import NeuroSync, TrainingConfig
# Train with default configuration
cipher = NeuroSync.train_new()
# Or with custom configuration
config = TrainingConfig(
training_episodes=10_000_000,
batch_size=128,
hidden_size=512,
)
cipher = NeuroSync.train_new(config)
# Save the trained models
cipher.save("./my_weights/")from NeuroSync import NeuroSync
cipher = NeuroSync.from_pretrained("./weights/")
# Create sender and receiver
sender = cipher.create_sender()
receiver = cipher.create_receiver()
# Set a message
msg = "Hello from NeuroSync!"
# Send and receive the message
while msg:
packets, msg = sender.send(msg)
for packet in packets:
message = receiver.receive(packet)
if message:
print(f"Received: {message}")
acks = receiver.get_pending_acks()
for ack in acks:
sender.handle_ack(ack)from NeuroSync import NeuroSyncTrainer, TrainingConfig
config = TrainingConfig(
# Message and key settings
message_length=16, # Characters per message chunk
key_size=16, # Key size in characters
# Training parameters
training_episodes=20_000_000,
batch_size=64,
learning_rate=0.0005,
# Network architecture
hidden_size=512,
num_residual_blocks=3,
dropout=0.05,
# Adversarial training
adversarial_max=0.15, # Maximum adversarial weight
eve_learning_rate=0.001,
eve_train_iterations=3,
# Security settings
security_max=0.1,
maintenance_threshold=99.0,
# Paths
data_dir="./data",
checkpoint_dir="./checkpoints",
word_list_file="words.txt",
)
trainer = NeuroSyncTrainer(config)
result = trainer.train()
result.save("./trained_models/")
print(f"Final accuracy: {result.final_accuracy:.2f}%")
print(f"Best accuracy: {result.best_accuracy:.2f}%")from NeuroSync import NeuroSync
cipher = NeuroSync.from_pretrained("./weights/")
sender = cipher.create_sender()
receiver = cipher.create_receiver()
# Send multiple messages
messages = [
"First message",
"Second message",
"Third message",
]
for msg in messages:
while msg:
packets, msg = sender.send(msg)
for packet in packets:
message = receiver.receive(packet)
if message:
print(f"Received: {message}")
acks = receiver.get_pending_acks()
for ack in acks:
sender.handle_ack(ack)import torch
from NeuroSync.core.networks import Alice, Bob, Eve
from NeuroSync.encoding.codec import text_to_bits, bits_to_text
from NeuroSync.crypto.operations import xor
from NeuroSync.crypto.keys import KeyManager
# Initialize networks
bit_length = 112 # 16 characters * 7 bits
alice = Alice(bit_length, hidden_size=512)
bob = Bob(bit_length, hidden_size=512)
# Load trained weights
alice.load("./weights/alice.pth")
bob.load("./weights/bob.pth")
# Set to evaluation mode
alice.eval()
bob.eval()
# Create key
key_manager = KeyManager()
key = key_manager.generate()
# Encrypt
plaintext = "Hello World! " # Pad to 16 chars
plain_bits = torch.tensor(text_to_bits(plaintext), dtype=torch.float32)
alice_input = xor(plain_bits, key)
with torch.no_grad():
ciphertext = alice(alice_input, single=True)
ciphertext = torch.sign(ciphertext)
# Decrypt
bob_input = xor(ciphertext, key)
decrypted_bits = bob(bob_input, single=True)
decrypted = bits_to_text(decrypted_bits)
print(f"Original: '{plaintext}'")
print(f"Decrypted: '{decrypted}'")import torch
from NeuroSync import NeuroSync
cipher = NeuroSync.from_pretrained("./weights/")
# Process multiple messages in a batch
messages = [
"Message one ",
"Message two ",
"Message three ",
]
# Create sender for batch processing
sender = cipher.create_sender()
all_packets = []
for msg in messages:
packets, _ = sender.send(msg)
all_packets.extend(packets)
print(f"Total packets: {len(all_packets)}")class NeuroSync:
@classmethod
def from_pretrained(cls, dirpath: str, device=None) -> "NeuroSync"
"""Load from pretrained weights directory."""
@classmethod
def train_new(cls, config=None, device=None) -> "NeuroSync"
"""Train a new NeuroSync system."""
def encrypt(self, plaintext: str) -> torch.Tensor
"""Encrypt a plaintext string."""
def decrypt(self, ciphertext: torch.Tensor) -> str
"""Decrypt an encrypted tensor."""
def create_sender(self) -> Sender
"""Create a Sender for full protocol usage."""
def create_receiver(self) -> Receiver
"""Create a Receiver for full protocol usage."""
def save(self, dirpath: str) -> None
"""Save weights to directory."""@dataclass
class TrainingConfig:
# Message settings
message_length: int = 16 # Characters per chunk
key_size: int = 16 # Key size in characters
# Training
training_episodes: int = 20_000_000
batch_size: int = 64
learning_rate: float = 0.0005
weight_decay: float = 1e-4
# Architecture
hidden_size: int = 512
num_residual_blocks: int = 3
dropout: float = 0.05
# Adversarial
adversarial_max: float = 0.15
eve_learning_rate: float = 0.001
# Paths
data_dir: str = "./data"
checkpoint_dir: str = "./checkpoints"class Sender:
def __init__(self, session, enable_error_correction=True, key_rotation_interval=50)
def send(self, message: str) -> Union[List[bytes], Optional[str]]:
"""Prepare message for transmission."""
def check_key_rotation(self) -> Optional[bytes]:
"""Check if key rotation is needed."""
def handle_ack(self, packet: bytes) -> None:
"""Handle acknowledgment packets."""class Receiver:
def __init__(self, session, enable_error_correction=True)
def receive(self, packet: bytes) -> Optional[str]:
"""Receive and process a packet."""
def get_pending_acks(self) -> List[bytes]:
"""Get pending acknowledgment packets."""
def has_pending_data(self) -> bool:
"""Check for pending data."""
def reset(self) -> None:
"""Reset receiver state."""Each network (Alice, Bob, Eve) uses the same base architecture:
Input (112 bits)
→ Linear(112, 512) + LayerNorm + Tanh
→ ResidualBlock × 3
→ Linear(512, 512) + LayerNorm + Tanh
→ Linear(512, 112) + Tanh/Temperature
Output (112 bits)
Each ResidualBlock contains:
- Linear layer with LayerNorm
- Tanh activation
- Dropout (5%)
- Residual connection
┌─────────────────────────────────────┐
│ Application │
│ (NeuroSync / Sender/Receiver) │
├─────────────────────────────────────┤
│ Session Layer │
│ (CryptoSession) │
├─────────────────────────────────────┤
│ Protocol Layer │
│ (Packets, Flags, Key/Weight Rot.) │
├─────────────────────────────────────┤
│ Encoding Layer │
│ (6-bit encoding, batch processing) │
├─────────────────────────────────────┤
│ Crypto Layer │
│ (Alice/Bob networks, XOR mixing) │
└─────────────────────────────────────┘
┌────────────────────────────────────────────┐
│ Header (12 bytes) │
│ ├─ Version (1 byte) │
│ ├─ Flags (1 byte) │
│ ├─ Sequence ID (4 bytes) │
│ ├─ Payload Length (2 bytes) │
│ └─ Checksum (4 bytes) │
├────────────────────────────────────────────┤
│ Payload (variable) │
│ └─ Encrypted message data │
├────────────────────────────────────────────┤
│ Parity (optional) │
│ └─ Error correction bits │
└────────────────────────────────────────────┘
Create a words.txt file with training words (one per line):
hello
world
neural
crypto
secure
...
The training process involves three phases:
- Warm-up Phase (first ~2000 batches): Duplicate messages to establish basic encryption
- Main Training: Full adversarial training with Eve providing security pressure
- Maintenance Mode: When accuracy reaches 99%+, reduce training to maintain stability
Training logs include:
- Bob's decryption accuracy (target: 99%+)
- Eve's decryption accuracy (should stay low)
- Security check scores (leakage, diversity, repetition, key sensitivity)
- Network temperatures
- Start with default configuration for baseline results
- Increase
hidden_sizefor more complex encryption patterns - Adjust
adversarial_maxto balance security vs. stability - Use a diverse word list for better generalization
- Training typically requires 10-20 million episodes for 99%+ accuracy
NeuroSync/
├── NeuroSync/
│ ├── __init__.py # Package exports
│ ├── version.py # Version info
│ ├── core/ # Neural network components
│ │ ├── networks.py # Alice, Bob, Eve networks
│ │ ├── layers.py # ResidualBlock, etc.
│ │ ├── activations.py # StraightThroughSign
│ │ └── losses.py # Custom loss functions
│ ├── crypto/ # Cryptographic operations
│ │ ├── keys.py # KeyManager
│ │ ├── weights.py # WeightManager
│ │ └── operations.py # XOR and mixing ops
│ ├── encoding/ # Message encoding
│ │ ├── codec.py # text_to_bits, bits_to_text
│ │ ├── batch.py # Batch processing
│ │ └── constants.py # MESSAGE_LENGTH, BIT_LENGTH
│ ├── interface/ # High-level interfaces
│ │ ├── cipher.py # NeuroSync main class
│ │ ├── sender.py # Sender interface
│ │ ├── receiver.py # Receiver interface
│ │ └── visualizer.py # Training visualization
│ ├── protocol/ # Communication protocol
│ │ ├── packet.py # Packet structure
│ │ ├── session.py # CryptoSession
│ │ ├── flags.py # PacketFlags
│ │ ├── header.py # PacketHeader
│ │ ├── key_rotation.py # Key rotation manager
│ │ ├── weight_rotation.py # Weight rotation manager in the future
│ │ ├── error_correction.py # Parity-based ECC
│ │ └── assembler.py # Packet reassembly
│ ├── security/ # Security analysis
│ │ ├── analyzer.py # SecurityAnalyzer
│ │ ├── checks.py # Security check functions
│ │ └── thresholds.py # SecurityThresholds
│ ├── training/ # Training pipeline
│ │ ├── trainer.py # NeuroSyncTrainer
│ │ ├── config.py # TrainingConfig
│ │ ├── state.py # TrainingState
│ │ ├── evaluation.py # Accuracy/security evaluation
│ │ └── schedulers.py # Learning rate schedulers
│ └── utils/ # Utilities
│ ├── device.py # CUDA/CPU detection
│ ├── io.py # File I/O helpers
│ ├── logging.py # Logging setup
│ └── timing.py # Performance timing
├── tests/ # Test suite
├── examples/ # Usage examples
├── docs/ # Documentation
├── pyproject.toml # Package configuration
└── README.md # This file
NeuroSync is a research project in a beta state, demonstrating neural cryptography concepts. While it implements several security features, it still isnt production-ready. Please consider the following:
- Not for Production: This is still a beta version so it is an experimental software not audited for production use
- Key Management: Secure key storage and transmission are the user's responsibility
- Side Channels: Not tested against timing or power analysis attacks
- Quantum Security: While it is designed to be quantum-resistant, it has not been formally analyzed against quantum attacks and is not yet ready for such scenarios
Use only for educational and research purposes, or at your own risk. (Before a new stable release is made available.) For production cryptography needs, use established libraries like cryptography or NaCl.
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
# Setup development environment
git clone https://github.com/CooDiiNgg/NeuroSync.git
cd NeuroSync
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black NeuroSync/
isort NeuroSync/
# Type checking
mypy NeuroSync/If you only have suggestions or bug reports, please open an issue on GitHub, or feel free to contact me directly. (Contact info is at the bottom of the page.)
This project is licensed under the MIT License - see the LICENSE file for details.
If you use NeuroSync in your research, please cite - it brings me great joy!
@software{neurosync2026,
author = {Valkanov, Nikolay},
title = {NeuroSync: Neural Cryptography Library},
year = {2026},
url = {https://github.com/CooDiiNgg/NeuroSync}
}- Inspired by Learning to Protect Communications with Adversarial Neural Cryptography by Abadi & Andersen (Google Brain)
- Built with PyTorch
For questions or support, please open an issue on GitHub or contact me at:
- Email: niki@valkanovi.com
- LinkedIn: Nikolay Valkanov