BitWell

A complete cryptographic toolkit for ComputerCraft. Modern algorithms, zero compromises.

Because your Minecraft world deserves more than textutils.serialize()

What You Get

Production-grade cryptography, written in pure Lua.

• 🔐 ChaCha20-Poly1305 - Authenticated encryption that actually prevents tampering
• ✍️ Ed25519 - Digital signatures for when you need proof
• 🤝 X25519 - Key exchange for secure channels between computers
• 🌊 SHA-256, SHA-512, BLAKE3 - Cryptographic hashing done right
• 🔑 PBKDF2 & HKDF - Turn passwords into keys, expand keys into hierarchies
• 🎲 ChaCha20-CSPRNG - Random numbers you can actually trust

Tested for 146 cases covering everything from "does it work?" and "what if I encrypt 1MB at once?" to "can it survive 100,000 iterations without crashing?"

Installation

Wget (recommended):

wget run https://github.com/edujime23/BitWell/releases/latest/download/installer.lua

Initializing the Random Number Generator

CC:T doesn't have /dev/urandom. so we can't read CPU jitter. So what we do is combine multiple entropy sources and put put it in something similar to a blender.

Option 1: Automatic (Recommended)

local BitWell = require("BitWell")

-- Uses all available entropy: system time, network timing, disk I/O jitter
local key = BitWell.generateKey(256)

Behind the scenes, BitWell:

1. Queries os.epoch() with microsecond precision
2. Measures HTTP request timing variance (if http is enabled)
3. Samples disk read timings
4. Hashes everything through ChaCha20
5. Continuously rekeys itself

Option 2: Network Entropy (Best Quality)

local Random = require("BitWell.random")

-- Uses random.org, ANU QRNG, or custom sources
Random.getInstance():addNetworkEntropy({
    "https://www.random.org/cgi-bin/randbyte?nbytes=32&format=h",
    "https://qrng.anu.edu.au/API/jsonI.php?length=32&type=hex8"
})

local key = BitWell.generateKey(256)

Option 3: Manual Seeding (You Control It)

local Random = require("BitWell.random")

-- Prompt user to mash keyboard (seriously, entropy is entropy)
print("Mash your keyboard randomly for 5 seconds...")
local entropy = ""
for i = 1, 50 do
    local event, key = os.pullEvent("key")
    entropy = entropy .. string.char(key) .. tostring(os.epoch("utc"))
end

Random.getInstance():addEntropy(entropy)

Option 4: Deterministic (Testing Only)

local Random = require("BitWell.random")

-- Repeatable random for unit tests
local rng = Random.deterministic("test-seed-12345")
-- ONLY WHEN TESTING!

Is It Secure?

It's secure for ComputerCraft.

• ✅ For protecting Minecraft data: Absolutely. It's overkill, actually.
• ✅ For rednet secure channels: YES
• ✅ For authentication: Yes, Ed25519 signatures work great.
• ✅ For password hashing: Yes, PBKDF2 with 100k iterations.

Quick Examples

Encrypt Player Data

local save = {gold = 10000, base = {x=1000,y=64,z=2000}}
local key = BitWell.generateKey(256)  -- Store this securely

local encrypted, tag = BitWell.encrypt(key, textutils.serialize(save), "player:Steve")
-- ...
local decrypted = BitWell.decrypt(key, tag, encrypted, "player:Steve")
if decrypted then
    local data = textutils.unserialize(decrypted)
else
    error("Data was tampered with!")
end

Sign Transactions

local Ed25519 = require("BitWell.protocols.signatures.ed25519")

local sk, pk = BitWell.generateSigningKeypair()

local transaction = {from="Alice", to="Bob", amount=500}
local signature = Ed25519.sign(sk, pk, textutils.serialize(transaction))

-- Anyone can verify:
if Ed25519.verify(pk, textutils.serialize(transaction), signature) then
    print("Transaction is authentic!")
end

Secure Communication

local X25519 = require("BitWell.elliptic.scalar_mult")

-- Alice generates keypair
local aliceSecret = BitWell.generateKey(256)
local alicePublic = X25519.publicKey(aliceSecret)

-- Bob generates keypair
local bobSecret = BitWell.generateKey(256)
local bobPublic = X25519.publicKey(bobSecret)

-- Both derive same shared secret
local aliceShared = X25519.exchange(aliceSecret, bobPublic)
local bobShared = X25519.exchange(bobSecret, alicePublic)
-- aliceShared == bobShared

-- Now use shared secret to encrypt messages
local msg, tag = BitWell.encrypt(aliceShared, "Hello Bob!", "")

Hash Passwords

local PBKDF2 = require("BitWell.protocols.kdf.pbkdf2")

-- During registration:
local salt = BitWell.generateKey(128)
local hash = PBKDF2.pbkdf2(password, salt, 100000)
-- ...
-- During login:
local loginHash = PBKDF2.pbkdf2(inputPassword, storedSalt, 100000)
if BitWell.utils.compare.compare(loginHash, storedHash) then
    print("Login successful")
end

What's Included

What	Where	Why
Main API	BitWell	One-line encrypt/decrypt/sign
Hash Functions	primitives.hash.*	SHA-256, SHA-512, BLAKE3
Encryption	primitives.symmetric.*	ChaCha20 stream cipher
Authentication	primitives.mac.*	Poly1305, HMAC
AEAD	protocols.aead	ChaCha20-Poly1305 combined
Signatures	protocols.signatures.*	Ed25519
Key Exchange	elliptic.scalar_mult	X25519
Key Derivation	protocols.kdf.*	PBKDF2, HKDF
Encoding	encoding.*	Base64, Hex, Armor
Random	random	ChaCha20-based CSPRNG

---

Made with ❤️ for ComputerCraft.