#mooncry

#Highlights

• Correct — every algorithm is checked against FIPS / NIST / RFC test vectors, and cross-validated against reference implementations (pycryptodome, cryptography, hashlib, libsodium, zlib) plus randomized differential testing. 1174 tests, run with moon test --deny-warn.
• Broad — MD5, SHA-1, the SHA-2 and SHA-3 families (incl. SHA-512/224 and SHA-512/256), Keccak-256, SHAKE/cSHAKE XOFs, KMAC128/256, BLAKE2b, BLAKE2s, BLAKE3, RIPEMD-160, HMAC (incl. HMAC-SHA3), Poly1305, CMAC-AES, keyed BLAKE2b/2s, GMAC, AES-CBC/GCM/CTR/CCM/KW/SIV, ChaCha20, Salsa20, ChaCha20-Poly1305 AEAD, XChaCha20 / XChaCha20-Poly1305 (24-byte nonce), HKDF, PBKDF2, scrypt, Argon2, RSA (PKCS1-v1.5/OAEP/PSS, incl. multi-hash _with variants**)**, ECDSA P-256 / secp256k1, SM2 (GB/T 32918, Chinese national standard), Ed25519 (incl. Ed25519ctx / Ed25519ph), Ed448 (incl. contexts), X25519 / X448, ML-KEM-512/768/1024 (FIPS 203 post-quantum KEM), HOTP/TOTP (incl. SHA-256/SHA-512 variants), SipHash-2-4, CRC32/CRC32C/CRC-64/Adler-32, a sealed-box AEAD envelope, Base64, Hex.
• Fast where it matters — hex / Base64 encoding are O(n); AES MixColumns uses precomputed GF(2^8) tables (~5x over bit-sliced math); throughput is measured by moon bench.
• Fail-fast on misuse, graceful on hostile input — AES / ChaCha20 / SHAKE / hex functions abort with a clear message on wrong key / IV / nonce / tag lengths instead of producing garbage. Where the content (not just the length) crosses a trust boundary — a peer's ciphertext, signature, public key, or an encoded blob — every failure is reported as a value instead: Bool (verifiers, GCM), Option (GCM-SIV, HPKE open, hybrid open), or Result (SIV, KW, sealed box, and the _or family below). A dedicated robustness suite fuzzes each of those entry points with truncated, extended, bit-flipped and wiped inputs.
• Graceful _or variants — hex_to_bytes_or, base64_decode_or, chacha20_poly1305_decrypt_or, xchacha20_poly1305_decrypt_or, aes_ccm_decrypt_or, aes_decrypt_cbc_or, sm4_cbc_decrypt_or, rsa_oaep_decrypt_or (+ _with_or / _crt_or), rsa_pkcs1_v15_decrypt_or (+ _crt_or), ml_kem_*_encaps_or / ml_kem_*_decaps_or, ml_kem_*_hybrid_seal_or (+ _seal_init_or), rsa_oaep_encrypt_or (+ _with_or) / rsa_pkcs1_v15_encrypt_or, sm2_encrypt_or / sm2_encrypt_with_k_or / sm2_seal_or, sm2_ct_to_der_or / sm2_sig_to_der_or / sm2_pk_to_spki_der_or / sm2_pk_to_pem_or, xwing_encaps_or / xwing_decaps_or, x25519_or / x448_or, and the HPKE *_or setup/encap/decap family return Result so network-facing code never traps on malformed input. The RSA decryption ones return a single uniform error for every padding failure (no Bleichenbacher/Manger oracle through error text).
• Single source of truth — one-shot hash entry points delegate to the streaming hashers, so the incremental and one-shot paths share one implementation.

The implementations are correct and tested but have not been formally audited. See Security & performance boundaries.

#Repositories

• GitHub (canonical): https://github.com/cc06b/mooncry
• Gitlink (mirror): https://www.gitlink.org.cn/CC01/mooncry_mirror

git remote add gitlink https://www.gitlink.org.cn/CC01/mooncry_mirror.git
git push gitlink master

#Algorithms

#Hash functions

• MD5 (RFC 1321) — 128-bit digest
• SHA-224 / SHA-256 (FIPS 180-4) — 224 / 256-bit digest
• SHA-384 / SHA-512 (FIPS 180-4) — 384 / 512-bit digest
• SHA-512/224 / SHA-512/256 (FIPS 180-4 §5.3.6) — truncated SHA-512 variants
• SHA-3 (FIPS 202) — SHA3-224 / 256 / 384 / 512 (Keccak-f[1600] sponge)
• Keccak-256 (original Keccak submission, domain 0x01) — the Ethereum hash
• BLAKE2b (RFC 7693) — 1..64-byte digest; keyed variant (MAC, 1..64-byte key)
• BLAKE2s (RFC 7693) — 1..32-byte digest (32-bit words, 64-byte blocks); keyed variant (MAC, 1..32-byte key)
• RIPEMD-160 (Dobbertin et al. 1996) — 160-bit digest (Bitcoin legacy)
• BLAKE3 (BLAKE3 spec) — 32-byte default digest, XOF (arbitrary-length via tree-Merkle)
• SM3 (GB/T 32905-2016) — Chinese national hash standard, 256-bit digest; streaming API (sm3_new/sm3_update/sm3_finalize)

#Extendable-output functions (XOF)

• SHAKE128 / SHAKE256 (FIPS 202) — variable-length output
• cSHAKE128 / cSHAKE256 (NIST SP 800-185) — customizable XOFs (function name N + customization string S; degenerate to SHAKE when both empty)

#Message authentication

• HMAC-SHA256 / HMAC-SHA512 (RFC 2104)
• HMAC-SHA3-256 / HMAC-SHA3-512 (RFC 2104 over FIPS 202)
• HMAC-SHA3-224 / HMAC-SHA3-384 (RFC 2104 over FIPS 202)
• Poly1305 (RFC 8439) — one-time MAC
• AES-CMAC (NIST SP 800-38B) — 128-bit tag, 128/192/256-bit keys
• KMAC128 / KMAC256 (NIST SP 800-185) — Keccak-based MAC with customization string; KMACXOF128 / KMACXOF256 variable-length variants
• GMAC (NIST SP 800-38D) — AES-GCM authentication-only mode (16-byte tag); one-shot and incremental (gmac_new / gmac_update / gmac_finalize)

#Symmetric ciphers / AEAD

• AES-CBC (NIST SP 800-38A) — PKCS#7 padding, 128/192/256-bit keys, IV prepended
• AES-GCM (NIST SP 800-38D) — authenticated encryption with AAD, 96-bit nonce
• AES-CCM (NIST SP 800-38C / RFC 3610) — CBC-MAC + CTR AEAD, 7..13-byte nonce, 4..16-byte tag
• Adler-32 (RFC 1950) — zlib rolling checksum
• AES-CTR (NIST SP 800-38A) — 128-bit big-endian counter, stream cipher
• ChaCha20 (RFC 8439) — 256-bit key, 96-bit nonce, stream cipher
• Salsa20 (eSTREAM, 20-round) — 16/32-byte key, 8-byte nonce, stream cipher
• ChaCha20-Poly1305 (RFC 8439) — AEAD (ciphertext || 16-byte tag)
• XChaCha20 (draft-irtf-cfrg-xchacha) — ChaCha20 with a 24-byte nonce via HChaCha20 subkey derivation
• XChaCha20-Poly1305 (draft-irtf-cfrg-xchacha / libsodium IETF) — AEAD with a 24-byte nonce (ciphertext || 16-byte tag)
• SM4 (GB/T 32907-2016) — Chinese national block cipher, 128-bit block/key, 32-round Feistel; single-block encrypt/decrypt with reusable round keys
• SM4-CTR / SM4-CBC / SM4-GCM — modes of operation (GCM reuses the cipher-independent GHASH); HMAC-SM3 (RFC 2104). Vectors cross-checked against openssl's SM4/SM3
• HKDF-SM3 / PBKDF2-SM3 (RFC 5869 / RFC 2898 over HMAC-SM3) and SM2 signature DER encode/decode (openssl ASN.1 form) — vectors from openssl
• SM2 key serialization — PKCS#8 / SPKI in DER and PEM, byte-identical to openssl 3.x encodings (verified against PEMs openssl produced and consumed); strict decoders with malformed-input rejection
• SM2 sealed envelope (GM/T 0009 style) — sm2_seal/sm2_open: fresh SM4 key + IV wrapped to the recipient, payload under SM4-GCM
• ZUC-128 (GM/T 0001.1-2012 / 3GPP TS 35.221) — the Chinese national stream cipher behind LTE/NR confidentiality and integrity: a 16-cell LFSR over GF(2^31−1), bit reorganization, and the F function with the S0/S1 S-boxes. Raw keystream and stream XOR are exposed directly
• 128-EEA3 (3GPP TS 35.222) — the ZUC confidentiality algorithm (f8): COUNT/BEARER/DIRECTION build the IV, and the output is masked to an exact bit length
• 128-EIA3 (3GPP TS 35.223) — the ZUC integrity algorithm (f9): bit-oriented MAC-I over the message, with a constant-time tag check (zuc_eia3_verify). Neither mode authenticates on its own; pair EEA3 with EIA3 the way PDCP does
• ZUC-256 (GM/T 0001.2 / TS 35.221 v17+) — the 256-bit-key variant: a 32-byte key and a 23-byte IV carrying eight 6-bit frame parameters, packed into the same engine. Keystream (zuc256_keystream), raw stream mode (zuc256_xor) and a MAC with a 32-, 64- or 128-bit tag (zuc256_mac, zuc256_mac_verify); the tag sizes are domain-separated by the D-matrix row, so a short tag is never a prefix of a longer one

#Key derivation

• HKDF-SHA256 (RFC 5869) — extract + expand
• HKDF-SHA512 (RFC 5869) — extract + expand over SHA-512
• HKDF-SHA3-256 (RFC 5869 over FIPS 202)
• PBKDF2-HMAC-SHA256 (RFC 8018) — password-based key derivation
• PBKDF2-HMAC-SHA1 (RFC 8018 / RFC 6070 vectors) — legacy KDF (WPA2)
• PBKDF2-HMAC-SHA512 (RFC 8018) — password-based key derivation
• PBKDF2-HMAC-SHA3-256 (RFC 8018 over FIPS 202)
• scrypt (RFC 7914) — memory-hard password-based KDF (Salsa20/8 + BlockMix + ROMix)

#Checksums / PRFs

• CRC32 (IEEE 802.3, poly 0xEDB88320 reflected)
• CRC32C (Castagnoli, poly 0x82F63B78 reflected) — iSCSI / ext4
• CRC-64/XZ (poly 0x42F0E1EBA9EA3693 reflected) — xz / lzma
• CRC-64/GO-ISO (poly 0x000000000000001B reflected) — Go hash/crc64 ISO
• SipHash-2-4 (Aumasson & Bernstein 2012) — 64-bit short-input PRF

#Composite envelope

• Sealed box — versioned AEAD envelope: HKDF-SHA256 (key derivation) + AES-256-GCM (AEAD). Wire format: version(1) ‖ nonce(12) ‖ ciphertext ‖ tag(16).

#Asymmetric (RSA)

• RSAES-PKCS1-v1.5 (RFC 8017 §7.2) — public-key encryption (decrypt is deterministic; encrypt takes caller-supplied padding randomness — no RNG)
• RSAES-OAEP (RFC 8017 §7.1) — SHA-256 + MGF1-SHA256 (decrypt deterministic; encrypt takes a caller-supplied 32-byte seed)
• RSASSA-PKCS1-v1.5 (RFC 8017 §8.2) — sign/verify over SHA-256 (deterministic)
• RSASSA-PSS (RFC 8017 §8.1) — SHA-256 + MGF1-SHA256, caller-supplied salt

#Asymmetric signatures (Ed25519)

• Ed25519 (RFC 8032, ed25519-sha-512) — deterministic sign/verify.
• Ed25519ctx / Ed25519ph (RFC 8032 §7.2/§7.3) — context-bound and pre-hashed variants (dom2 domain separation) Field arithmetic over GF(2^255-19) uses @bigint; the twisted-Edwards base point is recovered from y = 4/5. Signing is deterministic (no RNG).
• SM2 encryption (GB/T 32918.4) — C1||C3||C2 raw form plus DER (openssl ASN.1) encode/decode; SM3 counter KDF; cross-proven against openssl pkeyutl SM2 decrypt
• SM2 (GB/T 32918.2/.5) — Chinese national signature standard over sm2p256v1; SM3-based Z value binds signer ID, curve, and public key; raw r||s (64-byte) signatures; reuses the generic Barrett/Jacobian EC engine (SM2's a = p-3, the P-256 fast-doubling case)

#Key agreement (X25519)

• X25519 (RFC 7748) — Diffie-Hellman over Curve25519 via the x-coordinate-only Montgomery ladder. Reuses the GF(2^255-19) field ops.

#Encoding

• Base64 (RFC 4648) — standard alphabet with padding
• Hex — bytes ↔ lowercase hex

#Streaming API

#Installation

moon add cc06b/mooncry

#Quick start

moon new myapp
cd myapp
moon add cc06b/mooncry

import {
  "cc06b/mooncry/lib",
}

pkgtype(kind: "executable")

fn main {
  // SHA-256 one-shot
  let digest = @lib.sha256(b"Hello, world!")
  println("SHA-256: " + @lib.bytes_to_hex(digest))

  // AES-GCM round-trip (256-bit key, 96-bit nonce, with AAD)
  let key = Bytes::make(32, b'\x00')
  let iv = Bytes::make(12, b'\x00')
  let (ciphertext, tag) = @lib.aes_gcm_encrypt(b"secret data", key, iv, b"aad")
  let (plaintext, ok) = @lib.aes_gcm_decrypt(ciphertext, key, iv, b"aad", tag)
  let status = if ok { "OK" } else { "FAIL" }
  println("AES-GCM round-trip: " + status)
  println("Recovered: " + @lib.bytes_to_hex(plaintext))

  // Sealed-box envelope: HKDF-SHA256 derives the AES-256-GCM key from a
  // master key + context, then encrypts into a versioned envelope.
  let master = Bytes::make(32, b'\x07')
  let nonce = Bytes::make(12, b'\x01')
  let envelope = @lib.sealed_box_seal(master, nonce, b"plaintext", b"aad", b"tenant-1")
  match @lib.sealed_box_open(master, envelope, b"aad", b"tenant-1") {
    Ok(pt) => println("Sealed box: " + @lib.bytes_to_hex(pt))
    Err(msg) => println("Sealed box failed: " + msg)
  }
}

moon run cmd/main

SHA-256: 315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3
AES-GCM round-trip: OK
Recovered: 7365637265742064617461

#Public API

#Public but internal: what pub owes you here

#Security & performance boundaries

• Not audited. The code is correct against known vectors but has had no formal security review. Do not use it to protect high-value assets without an independent audit.
• AES is not constant-time. MixColumns uses precomputed GF(2^8) lookup tables (mul2/3/9/11/13/14) for ~5x throughput. This leaks key-dependent table indices through the CPU cache — acceptable for many use cases but not side-channel-safe against a local attacker. Since v0.19.0 GHASH also uses precomputed 4-bit tables (keyed by the GCM hash subkey), so it is no longer bit-sliced and is likewise not side-channel-safe; the GCM tag comparison and CBC PKCS#7 verification remain constant-time (no early exit on mismatch).
• ZUC is not constant-time. The F function looks up S0/S1 with indices derived from the key and IV, so keystream generation leaks through the CPU cache exactly the way AES's tables do (since v0.79.0 the two tables are widened to UInt64 at load — 4 KiB instead of 512 B — because the Byte→Int→UInt64 conversion on every lookup cost more than the extra cache footprint: ~1.4x on the stream paths). What is constant-time: the MAC rounds do not branch on message bits (the conditional XOR is a masked AND), and the tag comparisons (zuc_eia3_verify, zuc256_mac_verify) use bytes_equal and return false — never a trap — on a wrong-length tag. The keystream and MAC computations themselves are not side-channel-safe against a local attacker.
• Falcon keygen/sign are not constant-time. The port favours clarity and cross-platform bit-exactness over the C reference's constant-time discipline: the NTRU solver's bignum comparisons, conditional reductions, and rejection loops branch on secret-dependent values. Falcon verify only branches on public data (pk, signature, message). Keygen/sign run on the key owner's machine with freshly generated secrets; treat them as not side-channel-safe against local timing/cache attackers.
• Nonce reuse is catastrophic for AES-GCM and ChaCha20(-Poly1305). Never reuse a (key, nonce) pair. The library does not track nonces — generate a fresh one per message (e.g. a counter or CSPRNG).
• PBKDF2 is a KDF, not a password hasher. For interactive password storage prefer Argon2 / bcrypt / scrypt elsewhere; PBKDF2 is included for compatibility with existing protocols.
• MD5 is collision-broken. It is included for legacy compatibility only — do not sign or authenticate with it.
• BLAKE3 supports arbitrary-length input via the tree-Merkle mode (verified vs the reference blake3 Python package up to 5000 bytes).
• Inputs are validated, not silently padded. Wrong key / IV / nonce / tag lengths abort immediately rather than producing wrong output. That covers the signature schemes' key material too: slh_keygen (three n-byte seeds, n = 16/24/32), the six SLH signers (sk = 4n), ml_dsa_*_sign* (sk = the expanded length for the parameter set, from one shared helper), falcon512_keypair_from_seed / falcon1024_keypair_from_seed (48 bytes) and sm2_sign / sm2_sign_with_k (32 bytes). Before v0.81.0 those either read out of bounds — an unreachable trap with no message — or silently accepted the short input: slh_keygen returned a 63-byte secret key that only trapped later, at signing time, and Falcon derived full-length but non-standard keys from a 47-byte seed, which no other implementation reproduces.
• Numeric, enum and offset parameters are validated too (v0.84.0–v0.85.0). A length, a digit count or a block offset is the caller's business, so each aborts with a message instead of trapping or answering a different question: HKDF's length (≤ 255·HashLen, RFC 5869), PBKDF2's iterations (≥ 1, RFC 8018) and dklen, the output lengths of SHAKE / cSHAKE / KMAC / BLAKE2 / BLAKE3 / TurboSHAKE / KangarooTwelve (≥ 0) and of sha256_finalize_n / sha512_finalize_n (0..=32 / 0..=64, the contract their doc comments always stated), shake_finalize — the streaming twin the v0.84.0 one-shot guard did not cover — TurboSHAKE's domain byte (1..=127, RFC 9861 §2), sm4_encrypt_block / sm4_decrypt_block (32 round-key words, and an offset that leaves a whole block inside data), HPKE's mode (0..=3; any other value used to mean base mode, i.e. silently no authentication), ML-DSA's mu (exactly 64 bytes, FIPS 204), and HOTP/TOTP's digits (1..=9) and step (≥ 1 second). Two of those were worse than a trap: digits = 10 overflowed pow10 on a 32-bit target — 10^10 wraps to 1410065408 on wasm but is exact on native64, so one call gave two different OTPs depending on the target — and a negative step became a huge UInt64 (−30 → 18446744073709551586), quietly making every counter 0, i.e. the same OTP forever. Guards sit at the narrowest shared chokepoint (shake_check_out_len, turbosha_x, sm4_check_block_args, otp_check_digits / otp_check_step, kdf_check_expand_len, kdf_check_pbkdf2, hpke_check_mode, dsa_sk_len) so twins cannot drift, and each range's legal ends are pinned by a test — an over-tight guard turns it red.
• Untrusted input has a two-tier contract. Parameter shapes (a key of the wrong length, a nonce of the wrong size) are caller errors and abort loudly. Values that arrive from a peer — ciphertexts, signatures, public keys, encoded blobs — are never allowed to trap: verifiers return false, the Option/Result APIs return None/Err, and KEM decapsulation falls back to the implicit-rejection key. Every such entry point is covered by the hostile-input fuzz suite (see Testing); where the historical API aborted on an authentication failure, a graceful _or twin was added and the original kept for compatibility.
• Encrypting to a peer key crosses the same boundary as verifying one. Sealing and encrypting consume a recipient public key that came off the wire, so those entry points have _or twins too: ml_kem_*_hybrid_seal_or, rsa_oaep_encrypt_or / rsa_pkcs1_v15_encrypt_or and sm2_encrypt_or / sm2_seal_or report a degenerate modulus, a wrong-length encapsulation key, or a malformed / off-curve SM2 point as Err instead of trapping (an off-curve point is the invalid-curve attack surface). So does re-encoding what a peer sent: sm2_ct_to_der_or, sm2_sig_to_der_or, sm2_pk_to_spki_der_or and sm2_pk_to_pem_or take a raw ciphertext / signature / public key that may well have been truncated in transit. Each pair shares one shape check, so the aborting encoder and its twin cannot disagree about what counts as well-formed. rsa_pkcs1_v15_encrypt_or also rejects a zero byte inside rand_ps: RFC 8017 §7.2.1 requires nonzero octets, and accepting one would silently emit a ciphertext the recipient unpads to a truncated message.
• Some shape parameters are peer-derived. The tier above assumes a shape is the caller's business, which holds for a key or nonce length. It does not hold for a length field that a protocol puts on the wire: ZUC's LENGTH (the nbits argument of zuc_eea3_*, zuc_eia3_* and zuc256_mac*) comes from the PDCP/RRC header. A LENGTH that disagrees with the buffer it arrived in still aborts — silently MACing or encrypting a different message than the one received would be worse — so if your input can be truncated, check data.length() == (nbits + 7) / 8 before calling. Otherwise a peer can trigger the abort, and an abort in a long-lived process is a denial of service.
• Peer public keys are validated before ECDH. HPKE's NIST-curve KEMs (P-256/P-384/P-521) check that the peer point is in range and on the curve before the scalar multiply (hpke_valid_pk, also enforced inside hpke_dh); without it an attacker could send a point on a different, small-order curve and recover the private scalar a few bits per query (invalid-curve attack, RFC 9180 §7.1.3). ECDSA, SM2 sign/verify and SM2 decryption perform the same check. X25519/X448 deliberately accept any input (RFC 7748).
• RSA decryption errors are indistinguishable. rsa_oaep_decrypt_or and rsa_pkcs1_v15_decrypt_or return one uniform message for a wrong-length ciphertext, a bad first byte, a missing separator and an lHash mismatch, so the error channel cannot be used as a Bleichenbacher/Manger oracle. This does not make the padding side-channel-free — timing still differs, and CBC/PKCS#1 v1.5 remain unauthenticated: prefer an AEAD, and never expose the result to a peer without a MAC in front.
• No RNG. The library provides deterministic primitives; obtain keys, IVs, and nonces from a secure source.
• No unbounded loops. Every rejection-sampling loop that consumes caller-supplied randomness has an explicit attempt bound: Falcon signing (1000 attempts, then the empty-signature "cannot sign" signal), Falcon's discrete Gaussian sampler (10000, falling back to a sample the norm check rejects), and Falcon keygen's (f,g) / parity / range samplers (10000, then an abort, since the seed is local). ML-DSA signing (1000), ECDSA RFC 6979 (100), SM2 nonce draws (100) and HPKE's DeriveKeyPair (255, the width RFC 9180 gives the counter) were already bounded. With a working RNG none of these bounds is approached — Falcon signs in one or two attempts — but an unbounded loop over external input is a hang, and a hang is worse than an error: no message, no progress, and on wasm no way to interrupt it.

#Performance

moon bench

• The ZUC-256 MAC held its accumulator and key register in Array[UInt64], which costs a bounds-checked load and store per register word per message bit. Specialising the three tag sizes into local-variable registers: 1 KiB with a 128-bit tag 168 µs → 37.6 µs (4.5x), the same ratio in both rounds and under both load conditions.
• 128-EIA3's (K0, K1) pair packs into one UInt64, so sliding the register is a single 64-bit shift instead of two 32-bit shifts plus a merge (~1.15x on the MAC, and less code).
• S0/S1 widened from Array[Byte] to Array[UInt64] once at load, dropping a Byte→Int→UInt64 conversion from each of the eight lookups per clock: 1.35-1.45x on the stream paths for 4 KiB of table.
• The LFSR's 15-cell shift unrolled into constant-index copies: ~5% on an idle host, ~20% under load. Deleting the shift entirely measured no faster than the unrolled form, so the state stays a plain 16-cell array instead of becoming a ring buffer — which would have needed a new field in the public ZucState for nothing.
• Keystream XOR now runs word by word into the output buffer instead of materialising the whole keystream first: half the allocation, one pass.

#Testing

moon test

#Development

moon check --deny-warn
moon fmt --check
moon info
moon test --deny-warn
moon bench          # run the benchmark suite

#Publishing (maintainers)

moon login            # one time, with the account that owns cc06b
moon publish          # publishes the current version

#License