Crate kk_crypto 

KK, Keeney Kode

A novel cryptographic primitive where symbol values are temporal functions of universal entropy.

Core Principle

In all existing cryptography, symbol ‘A’ has a fixed value and encryption hides what ‘A’ means. In KK, symbol ‘A’ has no fixed value:

KK(S) = S^ε  where ε = universal entropy at moment of creation

The symbol’s fundamental value is a function of the universe at the instant it was born. The same symbol encoded twice produces two cryptographically unrelated values.

Quick Start

use kk_crypto::{encode, decode};

// Both parties share a secret
let shared_secret = b"our-shared-secret";

// Encode: symbol values become functions of this cosmic instant
let packet = encode(shared_secret, b"Hello KK!").unwrap();

// Transmit packet.to_bytes() to receiver...

// Decode: same secret, same moment reference, same values
let plaintext = decode(shared_secret, &packet).unwrap();
assert_eq!(plaintext, b"Hello KK!");

Architecture

Entropy Sources → KK-Mix → Per-Symbol Derivation → Temporal Binding → Encoding
    (entropy.rs)  (kk_mix.rs)    (kdf.rs)            (temporal.rs)     (codec.rs)

Every cryptographic operation is built from a single novel primitive: the KK permutation (Multiply-Fold-Rotate sponge construction). No SHA-256, no HKDF, no HMAC, 100% original KK.

Security Model

Threat model: KK assumes a pre-shared secret between sender and receiver. An attacker may observe, replay, or modify ciphertext in transit but does not know the shared secret.

Confidentiality: Each encoding captures a unique EntropySnapshot (CPU counters, thread jitter, OS randomness). The snapshot feeds the KK-KDF to derive per-chunk keystream, ensuring the same plaintext never produces the same ciphertext twice.

Integrity: Every KkPacket carries a KK-MAC tag over (ciphertext ‖ entropy snapshot). decode rejects any packet whose tag does not verify, preventing silent tampering.

Temporal binding: The TemporalCommitment in each packet commits to the entropy used during encoding. The receiver re-derives the commitment from the embedded snapshot and the shared secret, rejecting packets if the commitment does not match.

Key hygiene: Intermediate keys (commit keys, chunk keystream) are zeroized via the zeroize crate immediately after use. The output buffer is zeroized on error paths to prevent partial plaintext leaks.

Limitations:

• KK is a novel, un-audited primitive, it has not been reviewed by third-party cryptographers. Do not use for production security.
• The base codec has no forward secrecy. Use the session module’s Rope Ratchet (encode_session/decode_session) for ~192-bit forward secrecy via 4-strand ratcheting.
• Replay protection is not built in; callers must add sequence numbers or timestamps at the protocol layer.

J.A. Keeney, Australia, 2026

Re-exports

pub use codec::decode;

pub use codec::encode;

pub use codec::KkPacket;

pub use codec::decode_aead;

pub use codec::encode_aead;

pub use codec::KkAeadPacket;

pub use codec::decode_aead_batch;

pub use codec::encode_aead_batch;

pub use codec::decode_bound;

pub use codec::encode_bound;

pub use codec::KkBoundPacket;

pub use codec::decode_parallel;

pub use codec::encode_parallel;

pub use codec::KkParallelPacket;

pub use codec::PARALLEL_CHUNK_SIZE;

pub use codec::decode_split;

pub use codec::encode_split;

pub use codec::KkSealedMessage;

pub use codec::encode_aead_pooled;

pub use codec::encode_pooled;

pub use codec::StreamDecoder;

pub use codec::StreamEncoder;

pub use entropy::EntropySnapshot;

pub use entropy_pool::EntropyPool;

pub use error::KkError;

pub use temporal::generate_challenge;

pub use temporal::TemporalProof;

pub use temporal::GENESIS_MAC;

pub use session::decode_session;

pub use session::encode_session;

pub use session::RopePacket;

pub use session::RopeRatchet;

pub use session::RopeStep;

pub use session::decode_session_aead;

pub use session::encode_session_aead;

pub use session::RopeAeadPacket;

pub use qkd::alice_prepare;

pub use qkd::bob_measure;

pub use qkd::decrypt_epsilon;

pub use qkd::distill_key;

pub use qkd::encrypt_epsilon;

pub use qkd::eve_intercept;

pub use qkd::Basis;

pub use qkd::Bb84Result;

pub use qkd::Qubit;

pub use eka::EkaInitiator;

pub use eka::EkaMsg1;

pub use eka::EkaMsg2;

pub use eka::EkaMsg3;

pub use eka::EkaResponder;

pub use rng::KkRng;

pub use rng::KkRngPool;

Modules

codec

KK Codec, The core encoding/decoding primitive.

eka

KK Entropy Key Agreement (KK-EKA)

entropy

Multi-source entropy collection for KK.

entropy_pool

Pre-generated entropy pool for high-throughput encode paths.

error

kdf

Key derivation for KK.

kk_mix

KK-Mix v2: The novel cryptographic core of the KK system.

qkd

BB84 Quantum Key Distribution, Simulated Protocol

rng

KK-RNG: A deterministic random bit generator built entirely from the KK sponge.

session

KK Rope Ratchet: Forward Secrecy

temporal

Temporal commitment and proof system for KK.