CryptX(3)

💖 CryptX(3) 💖

okay bestie, this is the User Contributed Perl Documentation page for CryptX — literally the top-level distribution/doc page for a whole crypto toolkit, and it’s giving main character energy 👑✨. It mainly serves as the top-level distribution/documentation page. For actual work, use one of the concrete modules listed below.

🎀 NAME 🎀

CryptX — Cryptographic toolkit 🧰💅

✨ SYNOPSIS ✨

CryptX is the distribution entry point. In normal code, load one of the concrete modules listed below.

 ## one-shot hashing
 use Crypt::Digest qw(digest_data_hex);
 my $sha256 = digest_data_hex('SHA256', 'hello world');

 ## classic AES-CBC encryption with padding
 use Crypt::Mode::CBC;
 my $cbc = Crypt::Mode::CBC->new('AES');
 my $iv = random_bytes(16); # 16-byte AES block-size IV
 my $cbc_ciphertext = $cbc->encrypt('hello world', $key, $iv);

 ## authenticated encryption (AEAD) with AES
 use Crypt::AuthEnc::GCM qw(gcm_encrypt_authenticate);
 my $key = random_bytes(32);   # 32-byte AES-256 key
 my $nonce = random_bytes(12); # 12-byte unique nonce
 my ($ciphertext, $tag) = gcm_encrypt_authenticate('AES', $key, $nonce, 'header', 'hello world');

 ## message authentication
 use Crypt::Mac::HMAC qw(hmac_hex);
 my $mac = hmac_hex('SHA256', $key, 'hello world');

 ## secure random data + UUID helpers
 use Crypt::PRNG qw(random_bytes random_string);
 use Crypt::Misc qw(random_v4uuid random_v7uuid);
 my $salt = random_bytes(16);
 my $token = random_string(24);
 my $uuid4 = random_v4uuid();
 my $uuid7 = random_v7uuid();

 ## classic password-based key derivation
 use Crypt::KeyDerivation qw(pbkdf2);
 my $dk = pbkdf2('password', $salt, 100_000, 'SHA256', 32);

 ## bare stream cipher (authenticate separately)
 use Crypt::Stream::ChaCha;
 my $stream = Crypt::Stream::ChaCha->new($key, $nonce);
 my $stream_ciphertext = $stream->crypt('hello world');

 ## modern signatures
 use Crypt::PK::Ed25519;
 my $signer = Crypt::PK::Ed25519->new->generate_key;
 my $sig = $signer->sign_message('hello world');
 my $ok = $signer->verify_message($sig, 'hello world');

 ## key agreement
 use Crypt::PK::X25519;
 my $alice = Crypt::PK::X25519->new->generate_key;
 my $bob = Crypt::PK::X25519->new->generate_key;
 my $shared_secret = $alice->shared_secret($bob);

💖 DESCRIPTION 💖

Perl cryptographic modules built on the bundled LibTomCrypt (https://github.com/libtom/libtomcrypt) library. The distribution also includes Math::BigInt::LTM, a Math::BigInt backend built on the bundled LibTomMath (https://www.libtom.net/LibTomMath/) library used internally by LibTomCrypt 🧚✨.

This module mainly serves as the top-level distribution/documentation page. For actual work, use one of the concrete modules listed below.

🧭 Algorithm Selection Guide

🔐 Authenticated Encryption (AEAD)

For new designs, prefer authenticated encryption (AEAD) over bare cipher modes:

• ChaCha20-Poly1305 (Crypt::AuthEnc::ChaCha20Poly1305) — Fast, constant-time, widely deployed (TLS 1.3, WireGuard, SSH). Use this as the default AEAD choice.
• XChaCha20-Poly1305 (Crypt::AuthEnc::XChaCha20Poly1305) — Extended 24-byte nonce variant. Prefer over ChaCha20-Poly1305 when nonces are generated randomly.
• AES-GCM (Crypt::AuthEnc::GCM) — The standard AEAD mode for AES. Hardware-accelerated on modern CPUs. Requires unique nonces; nonce reuse breaks the security entirely.
• AES-SIV (Crypt::AuthEnc::SIV) — Deterministic AEAD, nonce-misuse resistant. Slightly slower but safer when nonce uniqueness cannot be guaranteed.
• AES-OCB (Crypt::AuthEnc::OCB) — Very fast single-pass AEAD. Check patent status for your jurisdiction.
• AES-EAX (Crypt::AuthEnc::EAX) — Two-pass AEAD based on CTR+OMAC. No patents, no nonce-length restrictions.
• AES-CCM (Crypt::AuthEnc::CCM) — Used in WiFi (WPA2) and Bluetooth. Requires knowing the plaintext length in advance.

🎲 Cryptographically Secure Randomness and UUIDs

• Random bytes / strings (Crypt::PRNG) — Use this for salts, keys, nonces, tokens, and any other secret random values. The functional helpers random_bytes, random_bytes_hex, random_bytes_b64, random_bytes_b64u, random_string, and random_string_from cover most use cases. The OO API and the algorithm-specific wrappers (Crypt::PRNG::ChaCha20, Crypt::PRNG::Fortuna, etc.) are mainly for deterministic streams or interoperability with a specific PRNG.
• UUIDs (random_v4uuid in Crypt::Misc, random_v7uuid in Crypt::Misc) — Use random_v4uuid for opaque random identifiers. Use random_v7uuid when you want roughly time-ordered identifiers that sort by creation time at millisecond granularity. UUIDs are identifiers, not replacements for secret random bytes.

🌊 Stream Ciphers

Stream ciphers encrypt data byte-by-byte without block padding. For most applications prefer an AEAD mode (see above) which bundles encryption with authentication. Use bare stream ciphers only when you handle authentication separately.

• ChaCha (Crypt::Stream::ChaCha) — The default stream cipher choice. Same core as ChaCha20-Poly1305 without the built-in MAC.
• XChaCha (Crypt::Stream::XChaCha) — Extended 24-byte nonce variant of ChaCha. Prefer when nonces are generated randomly.
• Salsa20 / XSalsa20 (Crypt::Stream::Salsa20, Crypt::Stream::XSalsa20) — Predecessor of ChaCha. Prefer ChaCha for new designs; Salsa20 only for interoperability (e.g. NaCl/libsodium).
• RC4 (Crypt::Stream::RC4) — Broken; do not use for new designs. Provided for legacy interoperability only.
• Rabbit, Sober128, Sosemanuk (Crypt::Stream::Rabbit, Crypt::Stream::Sober128, Crypt::Stream::Sosemanuk) — Niche ciphers from the eSTREAM portfolio. Use ChaCha unless a specific protocol requires one of these.

🧱 Block Cipher Modes (without authentication)

Use these only when authentication is handled separately or not needed:

• CTR (Crypt::Mode::CTR) — Turns a block cipher into a stream cipher. Parallelizable.
• CBC (Crypt::Mode::CBC) — Classic mode, needs padding. Prefer CTR or an AEAD mode.
• ECB (Crypt::Mode::ECB) — Insecure for most uses. Each block encrypted independently.

The individual Crypt::Cipher::AES, Crypt::Cipher::Twofish, etc. modules implement raw single-block encryption and are rarely used directly. In almost all cases you should use them through an AEAD mode (Crypt::AuthEnc::GCM, Crypt::AuthEnc::CCM) or a block cipher mode (Crypt::Mode::CBC, Crypt::Mode::CTR) instead. When choosing a cipher, AES is the default; it is hardware-accelerated on most modern CPUs.

#️⃣ Hash Functions

• SHA-256 / SHA-384 / SHA-512 (Crypt::Digest::SHA256, etc.) — The default choice for general hashing. Widely supported and well analyzed.
• SHA3-256 / SHA3-512 (Crypt::Digest::SHA3_256, etc.) — Alternative to SHA-2 with a completely different construction (Keccak sponge).
• BLAKE2b / BLAKE2s (Crypt::Digest::BLAKE2b_256, etc.) — Very fast, especially in software. BLAKE2b for 64-bit platforms, BLAKE2s for 32-bit.
• SHAKE / TurboSHAKE / KangarooTwelve — Extendable-output functions (XOFs). Use when you need variable-length output.

🧮 Checksums

Use Crypt::Checksum::CRC32 and Crypt::Checksum::Adler32 only for non-adversarial integrity checks such as accidental corruption detection. They are not cryptographic integrity or authenticity mechanisms. For cryptographic use, prefer Crypt::Digest, Crypt::Mac, or an AEAD mode from Crypt::AuthEnc.

🪪 Message Authentication Codes

• HMAC (Crypt::Mac::HMAC) — The standard MAC construction. Works with any hash. Use HMAC-SHA256 as the default.
• Poly1305 (Crypt::Mac::Poly1305) — One-time MAC, very fast. Used as part of ChaCha20-Poly1305. Requires a unique key per message.
• BLAKE2b-MAC (Crypt::Mac::BLAKE2b) — Keyed BLAKE2. Faster than HMAC-SHA256 in software.
• CMAC/OMAC (Crypt::Mac::OMAC) — Block-cipher-based MAC. Use when you already have AES but not a hash function.

🔑 Public-Key Cryptography

• Ed25519 (Crypt::PK::Ed25519) — Modern digital signatures. Fast, constant-time, small keys/signatures. The default choice for new signature schemes.
• Ed448 (Crypt::PK::Ed448) — Higher security margin than Ed25519 (~224-bit vs ~128-bit).
• X25519 (Crypt::PK::X25519) — Elliptic-curve Diffie-Hellman key agreement. The default choice for key exchange.
• X448 (Crypt::PK::X448) — Higher security margin than X25519.
• ECDSA (Crypt::PK::ECC) — Widely used (TLS, Bitcoin). Prefer Ed25519 for new designs unless ECDSA is required for interoperability.
• RSA (Crypt::PK::RSA) — Legacy but very widely used. Use 2048-bit keys minimum, 4096-bit preferred. Prefer OAEP for encryption and PSS for signatures.
• DSA (Crypt::PK::DSA) — Legacy. Prefer Ed25519 or ECDSA.
• DH (Crypt::PK::DH) — Classic Diffie-Hellman. Prefer X25519 for new designs.

🧬 Key Derivation / Password hashing

• HKDF (hkdf in Crypt::KeyDerivation) — Extract-then-expand KDF. Use for deriving keys from shared secrets (e.g. after ECDH).
• Argon2 (argon2_pbkdf in Crypt::KeyDerivation) — Memory-hard password hashing. The recommended choice for password storage.
• Bcrypt (bcrypt_pbkdf in Crypt::KeyDerivation) — Use mainly for compatibility with formats and protocols that specifically require bcrypt-based key derivation (for example some OpenSSH workflows). Prefer Argon2 for new password-storage designs.
• Scrypt (scrypt_pbkdf in Crypt::KeyDerivation) — Memory-hard KDF. Use Argon2 if available.
• PBKDF2 (pbkdf2 in Crypt::KeyDerivation) — Widely supported but CPU-only hardness. Use Argon2 or Scrypt when possible.
• PBKDF1 (pbkdf1 in Crypt::KeyDerivation, pbkdf1_openssl in Crypt::KeyDerivation) — Legacy derivation only. Keep this for interoperability with older formats; do not use it for new designs.

🚨 Error Handling

Most CryptX modules report errors by calling croak (from Carp). Invalid parameters, unsupported algorithms, wrong key sizes, malformed input, and internal library failures usually croak with a descriptive message. Catch exceptions with eval or Try::Tiny.

Some validation-style helpers use a return value instead of croaking. The most important examples are the *_decrypt_verify functions in the authenticated encryption modules Crypt::AuthEnc::*. These return undef when authentication fails, indicating the ciphertext was tampered with or the wrong key/nonce was used. Some parser/decoder helpers in other modules also return undef or false for malformed input, so check the concrete module POD when you need exact failure semantics.

🗺️ Module Map

• Top-level family modules
• Crypt::Cipher, Crypt::Mode, Crypt::AuthEnc, Crypt::Digest, Crypt::Mac, Crypt::Checksum, Crypt::PRNG, Crypt::PK, Crypt::KeyDerivation, Crypt::Misc, Crypt::ASN1 — the whole squad, right there 💜
• Symmetric ciphers 🔐

Crypt::Cipher::AES, Crypt::Cipher::Anubis, Crypt::Cipher::Blowfish, Crypt::Cipher::Camellia, Crypt::Cipher::CAST5, Crypt::Cipher::DES, Crypt::Cipher::DES_EDE, Crypt::Cipher::IDEA, Crypt::Cipher::KASUMI, Crypt::Cipher::Khazad, Crypt::Cipher::MULTI2, Crypt::Cipher::Noekeon, Crypt::Cipher::RC2, Crypt::Cipher::RC5, Crypt::Cipher::RC6, Crypt::Cipher::SAFERP, Crypt::Cipher::SAFER_K128, Crypt::Cipher::SAFER_K64, Crypt::Cipher::SAFER_SK128, Crypt::Cipher::SAFER_SK64, Crypt::Cipher::SEED, Crypt::Cipher::SM4, Crypt::Cipher::Serpent, Crypt::Cipher::Skipjack, Crypt::Cipher::Twofish, Crypt::Cipher::XTEA

• Block cipher modes 🧩

Crypt::Mode::CBC, Crypt::Mode::CFB, Crypt::Mode::CTR, Crypt::Mode::ECB, Crypt::Mode::OFB

• Stream ciphers 🌊

Crypt::Stream::RC4, Crypt::Stream::ChaCha, Crypt::Stream::XChaCha, Crypt::Stream::Salsa20, Crypt::Stream::XSalsa20, Crypt::Stream::Sober128, Crypt::Stream::Sosemanuk, Crypt::Stream::Rabbit

• Authenticated encryption modes 🛡️

Crypt::AuthEnc::CCM, Crypt::AuthEnc::EAX, Crypt::AuthEnc::GCM, Crypt::AuthEnc::OCB, Crypt::AuthEnc::ChaCha20Poly1305, Crypt::AuthEnc::XChaCha20Poly1305, Crypt::AuthEnc::SIV

• Hash functions 🫧

Crypt::Digest::BLAKE2b_160, Crypt::Digest::BLAKE2b_256, Crypt::Digest::BLAKE2b_384, Crypt::Digest::BLAKE2b_512, Crypt::Digest::BLAKE2s_128, Crypt::Digest::BLAKE2s_160, Crypt::Digest::BLAKE2s_224, Crypt::Digest::BLAKE2s_256, Crypt::Digest::CHAES, Crypt::Digest::MD2, Crypt::Digest::MD4, Crypt::Digest::MD5, Crypt::Digest::RIPEMD128, Crypt::Digest::RIPEMD160, Crypt::Digest::RIPEMD256, Crypt::Digest::RIPEMD320, Crypt::Digest::SHA1, Crypt::Digest::SHA224, Crypt::Digest::SHA256, Crypt::Digest::SHA384, Crypt::Digest::SHA512, Crypt::Digest::SHA512_224, Crypt::Digest::SHA512_256, Crypt::Digest::Tiger192, Crypt::Digest::Whirlpool, Crypt::Digest::Keccak224, Crypt::Digest::Keccak256, Crypt::Digest::Keccak384, Crypt::Digest::Keccak512, Crypt::Digest::SHA3_224, Crypt::Digest::SHA3_256, Crypt::Digest::SHA3_384, Crypt::Digest::SHA3_512, Crypt::Digest::SHAKE, Crypt::Digest::TurboSHAKE, Crypt::Digest::KangarooTwelve

• Checksums ✅

Crypt::Checksum::Adler32, Crypt::Checksum::CRC32

• Message authentication codes 🏷️

Crypt::Mac::BLAKE2b, Crypt::Mac::BLAKE2s, Crypt::Mac::F9, Crypt::Mac::HMAC, Crypt::Mac::OMAC, Crypt::Mac::Pelican, Crypt::Mac::PMAC, Crypt::Mac::XCBC, Crypt::Mac::Poly1305

• Public-key cryptography 🗝️

Crypt::PK::RSA, Crypt::PK::DSA, Crypt::PK::ECC, Crypt::PK::DH, Crypt::PK::Ed25519, Crypt::PK::X25519, Crypt::PK::Ed448, Crypt::PK::X448

• Cryptographically secure random number generators 🎲

Crypt::PRNG::Fortuna, Crypt::PRNG::Yarrow, Crypt::PRNG::RC4, Crypt::PRNG::Sober128, Crypt::PRNG::ChaCha20

• Key derivation functions 🌱

Crypt::KeyDerivation

• ASN.1 parser 📦

Crypt::ASN1

🧚 Only reach for Crypt::ASN1 when you actually need custom ASN.1 / DER parsing or encoding, okay? Like, most of the common key and certificate formats are already handled by the PK modules, so don't do extra work for no reason bestie.

• Miscellaneous helpers 🧰

Crypt::Misc (base64/base32/base58 codecs, PEM helpers, constant-time compare, UUID generation, octet increment helpers, and related utility functions) — the little grab-bag of useful stuff, lowkey iconic 💅

---

🩺 Diagnostic Functions

Okay so these are the low-level functions that spill all the details of the bundled LibTomCrypt build. They're for troubleshooting and bug reports, not for regular use — like, they're the backstage pass, not the main show 🙈

ltc_build_settings

my $str = CryptX::ltc_build_settings();

Returns a multi-line string describing every single compile-time option that was enabled when the bundled LibTomCrypt library was built (ciphers, hashes, MACs, PK algorithms, compiler flags, etc.). It's giving receipts ✨

ltc_mp_name

my $name = CryptX::ltc_mp_name();
# e.g. "LTM" (LibTomMath)

Returns the name of the math provider back-end in use 🔍

ltc_mp_bits_per_digit

my $bits = CryptX::ltc_mp_bits_per_digit();
# e.g. 60

Returns the number of bits per digit used by the math provider 🧮

---

🔢 Math::BigInt backend

So Math::BigInt::LTM is part of CryptX — it's a Math::BigInt backend built on the bundled LibTomMath library 🎀 It lives separate from all the cryptographic APIs up above, but it ships in the same distribution and runs on the exact same big-integer engine that LibTomCrypt relies on. Same house, different room bestie 🏠

---

📜 LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Periodt. 🫶

👑 COPYRIGHT

Copyright (c) 2013-2026 DCIT, a.s. <https://www.dcit.cz> / Karel Miko

---

And that's a wrap on the whole page, bestie 🎬💖 You just read the CryptX(3) manpage from the perl v5.42.0 docs, dated 2026-05-11 — go forth and encrypt responsibly ✨🔐🌸