CryptX(3) User Contributed Perl Documentation CryptX(3)
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:
o ChaCha20-Poly1305 (Crypt::AuthEnc::ChaCha20Poly1305) - Fast,
constant-time, widely deployed (TLS 1.3, WireGuard, SSH). Use this
as the default AEAD choice.
o XChaCha20-Poly1305 (Crypt::AuthEnc::XChaCha20Poly1305) - Extended
24-byte nonce variant. Prefer over ChaCha20-Poly1305 when nonces
are generated randomly.
o 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.
o AES-SIV (Crypt::AuthEnc::SIV) - Deterministic AEAD, nonce-misuse
resistant. Slightly slower but safer when nonce uniqueness cannot
be guaranteed.
o AES-OCB (Crypt::AuthEnc::OCB) - Very fast single-pass AEAD. Check
patent status for your jurisdiction.
o AES-EAX (Crypt::AuthEnc::EAX) - Two-pass AEAD based on CTR+OMAC. No
patents, no nonce-length restrictions.
o AES-CCM (Crypt::AuthEnc::CCM) - Used in WiFi (WPA2) and Bluetooth.
Requires knowing the plaintext length in advance.
Cryptographically Secure Randomness and UUIDs
o 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.
o 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.
o ChaCha (Crypt::Stream::ChaCha) - The default stream cipher choice.
Same core as ChaCha20-Poly1305 without the built-in MAC.
o XChaCha (Crypt::Stream::XChaCha) - Extended 24-byte nonce variant
of ChaCha. Prefer when nonces are generated randomly.
o Salsa20 / XSalsa20 (Crypt::Stream::Salsa20,
Crypt::Stream::XSalsa20) - Predecessor of ChaCha. Prefer ChaCha for
new designs; Salsa20 only for interoperability (e.g.
NaCl/libsodium).
o RC4 (Crypt::Stream::RC4) - Broken; do not use for new designs.
Provided for legacy interoperability only.
o 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:
o CTR (Crypt::Mode::CTR) - Turns a block cipher into a stream cipher.
Parallelizable.
o CBC (Crypt::Mode::CBC) - Classic mode, needs padding. Prefer CTR or
an AEAD mode.
o 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
o SHA-256 / SHA-384 / SHA-512 (Crypt::Digest::SHA256, etc.) - The
default choice for general hashing. Widely supported and well
analyzed.
o SHA3-256 / SHA3-512 (Crypt::Digest::SHA3_256, etc.) - Alternative
to SHA-2 with a completely different construction (Keccak sponge).
o BLAKE2b / BLAKE2s (Crypt::Digest::BLAKE2b_256, etc.) - Very fast,
especially in software. BLAKE2b for 64-bit platforms, BLAKE2s for
32-bit.
o 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
o HMAC (Crypt::Mac::HMAC) - The standard MAC construction. Works with
any hash. Use HMAC-SHA256 as the default.
o Poly1305 (Crypt::Mac::Poly1305) - One-time MAC, very fast. Used as
part of ChaCha20-Poly1305. Requires a unique key per message.
o BLAKE2b-MAC (Crypt::Mac::BLAKE2b) - Keyed BLAKE2. Faster than
HMAC-SHA256 in software.
o CMAC/OMAC (Crypt::Mac::OMAC) - Block-cipher-based MAC. Use when you
already have AES but not a hash function.
Public-Key Cryptography
o Ed25519 (Crypt::PK::Ed25519) - Modern digital signatures. Fast,
constant-time, small keys/signatures. The default choice for new
signature schemes.
o Ed448 (Crypt::PK::Ed448) - Higher security margin than Ed25519
(~224-bit vs ~128-bit).
o X25519 (Crypt::PK::X25519) - Elliptic-curve Diffie-Hellman key
agreement. The default choice for key exchange.
o X448 (Crypt::PK::X448) - Higher security margin than X25519.
o ECDSA (Crypt::PK::ECC) - Widely used (TLS, Bitcoin). Prefer Ed25519
for new designs unless ECDSA is required for interoperability.
o 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.
o DSA (Crypt::PK::DSA) - Legacy. Prefer Ed25519 or ECDSA.
o DH (Crypt::PK::DH) - Classic Diffie-Hellman. Prefer X25519 for new
designs.
Key Derivation / Password hashing
o HKDF ("hkdf" in Crypt::KeyDerivation) - Extract-then-expand KDF.
Use for deriving keys from shared secrets (e.g. after ECDH).
o Argon2 ("argon2_pbkdf" in Crypt::KeyDerivation) - Memory-hard
password hashing. The recommended choice for password storage.
o 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.
o Scrypt ("scrypt_pbkdf" in Crypt::KeyDerivation) - Memory-hard KDF.
Use Argon2 if available.
o PBKDF2 ("pbkdf2" in Crypt::KeyDerivation) - Widely supported but
CPU-only hardness. Use Argon2 or Scrypt when possible.
o 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
o Top-level family modules
Crypt::Cipher(3), Crypt::Mode(3), Crypt::AuthEnc(3), Crypt::Digest(3),
Crypt::Mac(3), Crypt::Checksum(3), Crypt::PRNG(3), Crypt::PK(3),
Crypt::KeyDerivation(3), Crypt::Misc(3), Crypt::ASN1(3)
o Symmetric ciphers
Crypt::Cipher::AES(3), Crypt::Cipher::Anubis(3), Crypt::Cipher::Blowfish(3),
Crypt::Cipher::Camellia(3), Crypt::Cipher::CAST5(3), Crypt::Cipher::DES(3),
Crypt::Cipher::DES_EDE(3), Crypt::Cipher::IDEA(3), Crypt::Cipher::KASUMI(3),
Crypt::Cipher::Khazad(3), Crypt::Cipher::MULTI2(3),
Crypt::Cipher::Noekeon(3), Crypt::Cipher::RC2(3), Crypt::Cipher::RC5(3),
Crypt::Cipher::RC6(3), Crypt::Cipher::SAFERP(3),
Crypt::Cipher::SAFER_K128(3), Crypt::Cipher::SAFER_K64(3),
Crypt::Cipher::SAFER_SK128(3), Crypt::Cipher::SAFER_SK64(3),
Crypt::Cipher::SEED(3), Crypt::Cipher::SM4(3), Crypt::Cipher::Serpent(3),
Crypt::Cipher::Skipjack(3), Crypt::Cipher::Twofish(3),
Crypt::Cipher::XTEA(3)
o Block cipher modes
Crypt::Mode::CBC(3), Crypt::Mode::CFB(3), Crypt::Mode::CTR(3),
Crypt::Mode::ECB(3), Crypt::Mode::OFB(3)
o Stream ciphers
Crypt::Stream::RC4(3), Crypt::Stream::ChaCha(3), Crypt::Stream::XChaCha(3),
Crypt::Stream::Salsa20(3), Crypt::Stream::XSalsa20(3),
Crypt::Stream::Sober128(3), Crypt::Stream::Sosemanuk(3),
Crypt::Stream::Rabbit(3)
o Authenticated encryption modes
Crypt::AuthEnc::CCM(3), Crypt::AuthEnc::EAX(3), Crypt::AuthEnc::GCM(3),
Crypt::AuthEnc::OCB(3), Crypt::AuthEnc::ChaCha20Poly1305(3),
Crypt::AuthEnc::XChaCha20Poly1305(3), Crypt::AuthEnc::SIV(3)
o Hash functions
Crypt::Digest::BLAKE2b_160(3), Crypt::Digest::BLAKE2b_256(3),
Crypt::Digest::BLAKE2b_384(3), Crypt::Digest::BLAKE2b_512(3),
Crypt::Digest::BLAKE2s_128(3), Crypt::Digest::BLAKE2s_160(3),
Crypt::Digest::BLAKE2s_224(3), Crypt::Digest::BLAKE2s_256(3),
Crypt::Digest::CHAES(3), Crypt::Digest::MD2(3), Crypt::Digest::MD4(3),
Crypt::Digest::MD5(3), Crypt::Digest::RIPEMD128(3),
Crypt::Digest::RIPEMD160(3), Crypt::Digest::RIPEMD256(3),
Crypt::Digest::RIPEMD320(3), Crypt::Digest::SHA1(3),
Crypt::Digest::SHA224(3), Crypt::Digest::SHA256(3),
Crypt::Digest::SHA384(3), Crypt::Digest::SHA512(3),
Crypt::Digest::SHA512_224(3), Crypt::Digest::SHA512_256(3),
Crypt::Digest::Tiger192(3), Crypt::Digest::Whirlpool(3),
Crypt::Digest::Keccak224(3), Crypt::Digest::Keccak256(3),
Crypt::Digest::Keccak384(3), Crypt::Digest::Keccak512(3),
Crypt::Digest::SHA3_224(3), Crypt::Digest::SHA3_256(3),
Crypt::Digest::SHA3_384(3), Crypt::Digest::SHA3_512(3),
Crypt::Digest::SHAKE(3), Crypt::Digest::TurboSHAKE(3),
Crypt::Digest::KangarooTwelve(3)
o Checksums
Crypt::Checksum::Adler32(3), Crypt::Checksum::CRC32(3)
o Message authentication codes
Crypt::Mac::BLAKE2b(3), Crypt::Mac::BLAKE2s(3), Crypt::Mac::F9(3),
Crypt::Mac::HMAC(3), Crypt::Mac::OMAC(3), Crypt::Mac::Pelican(3),
Crypt::Mac::PMAC(3), Crypt::Mac::XCBC(3), Crypt::Mac::Poly1305(3)
o Public-key cryptography
Crypt::PK::RSA(3), Crypt::PK::DSA(3), Crypt::PK::ECC(3), Crypt::PK::DH(3),
Crypt::PK::Ed25519(3), Crypt::PK::X25519(3), Crypt::PK::Ed448(3),
Crypt::PK::X448(3)
o Cryptographically secure random number generators
Crypt::PRNG::Fortuna(3), Crypt::PRNG::Yarrow(3), Crypt::PRNG::RC4(3),
Crypt::PRNG::Sober128(3), Crypt::PRNG::ChaCha20(3)
o Key derivation functions
Crypt::KeyDerivation(3)
o ASN.1 parser
Crypt::ASN1(3)
Use "Crypt::ASN1" only when you need custom ASN.1 / DER parsing or
encoding. Most common key and certificate formats are already
handled by the PK modules.
o Miscellaneous helpers
Crypt::Misc(3) (base64/base32/base58 codecs, PEM helpers,
constant-time compare, UUID generation, octet increment helpers,
and related utility functions)
Diagnostic Functions
These low-level functions expose details of the bundled LibTomCrypt
build. They are intended for troubleshooting and bug reports, not for
regular use.
ltc_build_settings
my $str = CryptX::ltc_build_settings();
Returns a multi-line string describing every compile-time option that
was enabled when the bundled LibTomCrypt library was built (ciphers,
hashes, MACs, PK algorithms, compiler flags, etc.).
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
Part of CryptX is Math::BigInt::LTM, a Math::BigInt backend based on
the bundled LibTomMath library. It is separate from the cryptographic
APIs above, but it ships in the same distribution and uses the same
big-integer engine that LibTomCrypt relies on.
LICENSE
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
COPYRIGHT
Copyright (c) 2013-2026 DCIT, a.s. <https://www.dcit.cz> / Karel Miko
perl v5.34.3 2026-05-11 CryptX(3)
cryptx 0.89.0 - Generated Tue May 12 13:11:46 CDT 2026