Add Post-Quantum Cryptography Support

[LucasMLK]

Post-Quantum Cryptography Support

This document explains the experimental Dilithium post-quantum signature support recently added to xdagj-crypto.

Overview

• Algorithm: CRYSTALS-Dilithium (NIST PQC finalist and selected signature scheme)
• Variants: Dilithium2 / Dilithium3 / Dilithium5 (default: Dilithium3)
• Implementation: Provided by the BouncyCastle crystals-dilithium module (JDK 21 compatible)
• Status: Experimental – not wired into XDAG consensus yet, intended for research/testing

Key Features

Capability	Description
Deterministic key derivation	Dilithium keys can be derived from existing XDAG BIP39 mnemonics using SHAKE-256 domain separation
Secure randomness	Falls back to the platform’s SecureRandom; deterministic derivation uses a SHAKE-256 stream
Signing & verification	High level DilithiumSigner class for signing and verifying arbitrary messages
Parameter selection	DilithiumParameter exposes Dilithium2/3/5 to trade off key size vs. security
Test coverage	JUnit tests cover random generation, mnemonic derivation, signature verification, and tampering

Usage Examples

import io.xdag.crypto.postquantum.dilithium.*;
import org.apache.tuweni.bytes.Bytes;

// 1. Random key generation (Dilithium3 by default)
DilithiumKeyPair keyPair = DilithiumSigner.generate();

// 2. Deterministic key derivation from XDAG mnemonic
String mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
DilithiumKeyPair deterministicPair =
        DilithiumSigner.generate(DilithiumParameter.DILITHIUM2);

// 3. Sign and verify a message
Bytes message = Bytes.fromUtf8String("XDAG PQ test");
DilithiumSignature signature = DilithiumSigner.sign(message, keyPair);
boolean isValid = DilithiumSigner.verify(message, signature, keyPair);

// 4. Using BIP44 wallet helper for mnemonic-based derivation
DilithiumKeyPair walletPair = Bip44Wallet.createDilithiumKeyPairFromMnemonic(mnemonic);

Key Classes

• DilithiumParameter – wraps BouncyCastle parameter sets and exposes security level metadata
• DilithiumKeyPair – immutable container for Dilithium public/private key material
• DilithiumSignature – lightweight wrapper around raw signature bytes
• DilithiumSigner – signing/verification helpers (random or mnemonic-based key derivation)
• HashUtils.shake256 – SHAKE-256 helper used for deterministic entropy expansion
• Bip44Wallet – new helpers to create Dilithium key pairs from seeds/mnemonics

Testing

Run the standard Maven test suite (JUnit 5):

mvn test

DilithiumSignerTest validates:

• Random key generation and signature verification
• Detection of tampered signatures
• Deterministic derivation from the canonical BIP39 test mnemonic

Total test count after PQ additions: 214 tests.

Observations & Limits

• Signature and key sizes are significantly larger than ECDSA/Schnorr; ensure downstream protocols can handle the payload.
• Performance is slower than traditional ECC but acceptable for experimentation; consider benchmarking before production use.
• Protocol integration is pending – transactions, consensus, and serialization formats would need extensions to embed Dilithium signatures.
• Security relies on the upstream BouncyCastle implementation; review BC release notes for potential updates or fixes.

Roadmap Ideas

1. Add serialization helpers (e.g., Base64 / CBOR) for Dilithium keys and signatures.
2. Provide multi-parameter derivation strategies (e.g., different domain separation tags for roles).
3. Explore multi-signature or threshold constructions built on Dilithium or other PQ-friendly schemes.
4. Integrate PQ signatures into XDAG transaction validation (requires protocol changes and community consensus).

---

For questions or proposals related to PQ support, open an issue or a discussion thread in the repository.