Nocturne-KX

Modern end-to-end cryptographic communication toolkit

---

Overview

Nocturne-KX is a security-focused framework for building secure messaging and communication systems. It combines authenticated key exchange, forward secrecy, and a Double Ratchet core with practical operational features including replay protection, rate limiting, audit logging, and HSM-backed key storage.

Key design goals:

• Clear security boundaries and conservative defaults
• Strict use of modern cryptographic primitives from libsodium
• Production-oriented operational features (audit, rotation, monitoring)
• Transparent, well-documented behavior

Current Status: Alpha/Prototype - suitable for research, demos, and experimentation. Not production-ready without comprehensive security audit and additional hardening.

---

Features

Core Cryptography

• X25519 ECDH for key agreement
• XChaCha20-Poly1305 AEAD for authenticated encryption
• Ed25519 for identity signatures
• BLAKE2b for transcript hashing
• Argon2 for passphrase-based key protection

Protocol Capabilities

• Authenticated SIGMA-style handshake with transcript binding and Ed25519 identity signatures
• Double Ratchet core with DH ratchet, send/receive chains, skipped key storage, out-of-order message handling, and state serialization
• Transport layer supporting NEGOTIATE/DATA/ACK/NAK/CLOSE frames, sequence numbers, retry queues, and feature negotiation
• In-memory adapter included for testing and development

Operational Security

• ReplayDB: Composite keys (receiver/sender/session), encrypted metadata, atomic writes with MAC protection, anti-rollback version counter, TPM counter support
• Rate Limiter: Token-bucket algorithm with JSONL persistence, exponential backoff, configurable burst limits
• Audit Logger: Hash-chained tamper-evident logging, Ed25519 digital signatures, WORM storage, SIEM integration support (Syslog, CEF, Splunk, ELK, Kafka)
• Key Rotation Manager: Time/count/volume-based rotation triggers, dual-control approval workflow, HSM-backed key storage, comprehensive audit trail
• HSM Integration: Abstract HSM interface, PKCS#11 wrapper, FileHSM with passphrase-encrypted keys

Side-Channel Protection

• Constant-time comparisons (sodium_memcmp)
• Secure memory zeroing (sodium_memzero)
• SecureAllocator with memory locking, guard pages, and scrubbing
• Branchless constant-time helpers
• Optional random delay (configurable/disableable)
• Cache line flushing and memory barriers

---

Architecture

Application
  │
  ├─ Handshake (SIGMA-style, Ed25519 identities, X25519 ephemeral)
  │     └─ Transcript hashing, two-way KDF
  │
  ├─ Double Ratchet (DH ratchet, chains, skipped keys)
  │
  └─ Transport (negotiate, seq/ACK/NAK, retry) ── In-memory adapter
        │
        ├─ ReplayDB (encrypted metadata, rollback protection)
        ├─ RateLimiter (persistent, token-bucket)
        ├─ AuditLogger (hash-chained, signed, WORM)
        ├─ KeyRotationManager (dual-control, HSM-backed)
        └─ HSM Interface (FileHSM, PKCS#11)

---

Quick Start

Prerequisites

• C++23 compiler: GCC 12+, Clang 15+, or MSVC 2022
• CMake 3.20+
• libsodium 1.0.18+
• Catch2 3.x (optional, for tests)

Installation

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y libsodium-dev pkg-config cmake build-essential

macOS

brew install libsodium pkg-config cmake

Windows (vcpkg)

vcpkg install libsodium:x64-windows

Build

# Clone repository
git clone https://github.com/Bufffer/Nocturne-KX.git
cd Nocturne-KX

# Configure and build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j

# Run tests (optional)
ctest --output-on-failure

Windows-specific build:

cmake .. -DCMAKE_TOOLCHAIN_FILE=[path-to-vcpkg]/scripts/buildsystems/vcpkg.cmake

---

Usage

Key Management

# Generate receiver key pair (X25519)
./nocturne-kx gen-receiver keys/

# Generate signer key pair (Ed25519)
./nocturne-kx gen-signer keys/

# Generate signer key with passphrase-encrypted storage (FileHSM)
./nocturne-kx gen-signer keys/ --hsm-pass "your-secure-passphrase"

Protocol Demos

# Handshake demo
./nocturne-kx hs-demo
# Demonstrates: authenticated handshake, identity signatures,
# transcript hashing, key derivation

# Double Ratchet demo
./nocturne-kx dr-demo
# Demonstrates: DH ratchet, message keys, out-of-order handling,
# state serialization

Encrypt / Decrypt

# Basic encryption
./nocturne-kx encrypt \
  --rx-pk keys/receiver_x25519_pk.bin \
  --in message.txt \
  --out encrypted.bin

# Decryption with replay protection
./nocturne-kx decrypt \
  --rx-pk keys/receiver_x25519_pk.bin \
  --rx-sk keys/receiver_x25519_sk.bin \
  --replay-db /path/to/replay.db \
  --mac-key /path/to/mac.key \
  --in encrypted.bin \
  --out decrypted.txt

Advanced Features

Digital Signatures (FileHSM)

./nocturne-kx encrypt \
  --rx-pk keys/receiver_x25519_pk.bin \
  --sign-hsm-uri file://keys/sender_ed25519_sk.bin \
  --in message.txt \
  --out encrypted_signed.bin

Rate Limiting

./nocturne-kx encrypt \
  --rx-pk keys/receiver_x25519_pk.bin \
  --rate-limit-store /path/to/rate_limits.jsonl \
  --in message.txt \
  --out encrypted.bin

Audit Logging (Signed and Hash-Chained)

# Enable audit log with Ed25519 signing and WORM output
./nocturne-kx encrypt \
  --rx-pk keys/receiver_x25519_pk.bin \
  --audit-log logs/audit.jsonl \
  --audit-sign-key keys/audit_ed25519_sk.bin \
  --audit-worm-dir logs/worm \
  --in message.txt \
  --out encrypted.bin

# With external timestamp anchor (RFC 3161 TSA token)
./nocturne-kx encrypt \
  --rx-pk keys/receiver_x25519_pk.bin \
  --audit-log logs/audit.jsonl \
  --audit-sign-key keys/audit_ed25519_sk.bin \
  --audit-anchor anchors/tsa_token.bin \
  --in message.txt \
  --out encrypted.bin

ReplayDB with TPM Counter

# Use ReplayDB with external monotonic counter for rollback detection
./nocturne-kx encrypt \
  --rx-pk keys/receiver_x25519_pk.bin \
  --replay-db state/replay.bin \
  --mac-key state/replay.mac \
  --tpm-counter state/tpm_counter.bin \
  --in message.txt \
  --out encrypted.bin

Global CLI Flags

• --rate-limit-store <path>: Persist token-bucket state
• --audit-log <path>: JSONL audit log path
• --audit-sign-key <path>: Ed25519 secret key for signing audit entries
• --audit-anchor <path>: External timestamp anchor blob
• --audit-worm-dir <dir>: Write-once-read-many directory
• --tpm-counter <path>: External monotonic counter (8-byte LE)
• --hsm-pass <passphrase>: Passphrase for FileHSM-encrypted keys

---

Deployment

Docker

# Build image
docker build -t nocturne-kx:3.0.0 .

# Run container
docker run --rm -it \
  -v $(pwd)/keys:/keys:ro \
  -v $(pwd)/state:/state \
  nocturne-kx:3.0.0 gen-receiver /keys

# Security scan
trivy image nocturne-kx:3.0.0

# SBOM generation
syft nocturne-kx:3.0.0 -o spdx-json > sbom.json

Docker Compose

docker-compose up -d

Kubernetes

# Deploy
kubectl apply -f k8s/deployment.yaml

# Check status
kubectl get pods -l app=nocturne-kx

# View logs
kubectl logs -f deployment/nocturne-kx

---

Documentation

• Security Guide: docs/SECURITY.md

  • Cryptographic primitives documentation
  • Threat model analysis
  • Security limitations and best practices
  • Deployment considerations

• Operations Guide: docs/OPERATIONS.md

  • Installation and configuration
  • Deployment guides (Systemd, Docker, Kubernetes)
  • Monitoring setup (Prometheus, Grafana)
  • Maintenance procedures and troubleshooting
  • Compliance considerations (FIPS, GDPR, ISO 27001)

---

Status & Roadmap

Current Status

• Alpha/Prototype: Suitable for research, demos, and experimentation
• Not production-hardened: Subject to change without formal security review

Known Limitations

• Real transport adapters (TCP/QUIC) not yet implemented - currently in-memory only
• PKCS#11 HSM integration is stubbed - requires production implementation
• SIEM connectors are framework only - actual implementations needed
• No formal security audit or penetration testing conducted
• No quantum-resistant cryptography (acknowledged design limitation)

Roadmap

• Complete transport layer implementations (TCP, QUIC, WebSocket)
• Production PKCS#11 HSM integration
• SIEM connector implementations (Splunk HEC, Elasticsearch, Kafka)
• Comprehensive integration and load testing
• Performance optimization and benchmarking
• Metrics and observability (Prometheus, OpenTelemetry)
• Enhanced operational tooling (health checks, automated rotation)
• Formal security audit and penetration testing
• FIPS 140-2/3 certification path
• Noise protocol integration
• Post-quantum cryptography exploration

---

Security Notice

⚠️ IMPORTANT: This software is provided as an alpha/prototype. It has not undergone formal security review or audit.

Do NOT deploy in production without:

• Comprehensive independent security audit
• Penetration testing
• Appropriate compliance processes (SOC 2, ISO 27001, etc.)
• Formal security validation for your specific use case

For production deployments:

• Use real HSMs (PKCS#11) - FileHSM is for development only
• Implement proper key management and backup procedures
• Enable comprehensive audit logging and monitoring
• Follow NIST SP 800-57 key management guidelines
• Conduct regular security assessments

Reporting Security Issues: If you discover a security vulnerability, please email: serdarogluibrahim@gmail.com

Do not open public GitHub issues for security vulnerabilities.

---

Testing

Unit Tests

# Build with tests
cmake .. -DENABLE_TESTING=ON
cmake --build . -j

# Run tests
ctest --output-on-failure

# Run with verbose output
ctest -V

CI/CD Pipeline

The project includes comprehensive CI/CD workflows:

• Build jobs: Release + Debug builds with sanitizers (ASAN, UBSAN, MSAN)
• Security scans: CodeQL, Trivy, cppcheck, Scorecard
• SBOM generation: syft (SPDX, CycloneDX)
• Dependency scanning: Grype
• Secret scanning: Gitleaks, TruffleHog

See .github/workflows/ for details.

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with clear commit messages
4. Add tests for new functionality
5. Ensure all tests pass and security scans are clean
6. Submit a pull request

Before contributing:

• Review docs/SECURITY.md
• Follow C++23 best practices
• Use libsodium for all cryptographic operations
• Add appropriate error handling and input validation
• Include documentation for new features

---

Intellectual Property

Copyright © 2025 Halil İbrahim Serdaroğlu. All rights reserved.

Ownership

This software is the exclusive intellectual property of Halil İbrahim Serdaroğlu.

Patents

• Patent Pending: Hybrid Post-Quantum Key Encapsulation Mechanism (Turkey Patent Office)
• Patent Pending: Bidirectional Replay Protection with Prefix-Based Counter Separation

Trademarks

• Nocturne-KX™ is a trademark of Halil İbrahim Serdaroğlu

Trade Secrets

Certain implementation details, optimizations, and security configurations are proprietary trade secrets.

---

License

MIT License - see LICENSE file for details.

Important: While the code is open source under MIT License, the name "Nocturne-KX™" is a registered trademark. Patent rights are reserved for specific innovations described in patent applications.

---

Contact

Author: Halil İbrahim Serdaroğlu Email: serdarogluibrahim@gmail.com GitHub: @Bufffer

For general questions, feature requests, or bug reports (non-security), please open a GitHub issue.

For commercial licensing inquiries, contact directly via email.

---

Acknowledgments

Built with:

• libsodium - Modern cryptographic library
• Catch2 - Testing framework
• CMake - Build system

Inspired by:

• Signal Protocol's Double Ratchet
• Noise Protocol Framework
• SIGMA key exchange protocols
• NIST cryptographic standards

---

_{Built with ❤️ for secure communications}