.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "CryptX 3" .TH CryptX 3 2026-08-10 "perl v5.42.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME CryptX \- Cryptographic toolkit .SH SYNOPSIS .IX Header "SYNOPSIS" CryptX is the distribution entry point. In normal code, load one of the concrete modules listed below. .PP .Vb 3 \& ## one\-shot hashing \& use Crypt::Digest qw(digest_data_hex); \& my $sha256 = digest_data_hex(\*(AqSHA256\*(Aq, \*(Aqhello world\*(Aq); \& \& ## classic AES\-CBC encryption with padding \& use Crypt::Mode::CBC; \& my $cbc = Crypt::Mode::CBC\->new(\*(AqAES\*(Aq); \& my $iv = random_bytes(16); # 16\-byte AES block\-size IV \& my $cbc_ciphertext = $cbc\->encrypt(\*(Aqhello world\*(Aq, $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(\*(AqAES\*(Aq, $key, $nonce, \*(Aqheader\*(Aq, \*(Aqhello world\*(Aq); \& \& ## message authentication \& use Crypt::Mac::HMAC qw(hmac_hex); \& my $mac = hmac_hex(\*(AqSHA256\*(Aq, $key, \*(Aqhello world\*(Aq); \& \& ## 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(\*(Aqpassword\*(Aq, $salt, 100_000, \*(AqSHA256\*(Aq, 32); \& \& ## bare stream cipher (authenticate separately) \& use Crypt::Stream::ChaCha; \& my $stream = Crypt::Stream::ChaCha\->new($key, $nonce); \& my $stream_ciphertext = $stream\->crypt(\*(Aqhello world\*(Aq); \& \& ## modern signatures \& use Crypt::PK::Ed25519; \& my $signer = Crypt::PK::Ed25519\->new\->generate_key; \& my $sig = $signer\->sign_message(\*(Aqhello world\*(Aq); \& my $ok = $signer\->verify_message($sig, \*(Aqhello world\*(Aq); \& \& ## 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); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" Perl cryptographic modules built on the bundled LibTomCrypt library. The distribution also includes Math::BigInt::LTM, a Math::BigInt backend built on the bundled LibTomMath library used internally by LibTomCrypt. .PP This module mainly serves as the top\-level distribution/documentation page. For actual work, use one of the concrete modules listed below. .SS "Algorithm Selection Guide" .IX Subsection "Algorithm Selection Guide" \fIAuthenticated Encryption (AEAD)\fR .IX Subsection "Authenticated Encryption (AEAD)" .PP For new designs, prefer authenticated encryption (AEAD) over bare cipher modes: .IP \(bu 4 \&\fBChaCha20\-Poly1305\fR (Crypt::AuthEnc::ChaCha20Poly1305) \- Fast, constant\-time, widely deployed (TLS 1.3, WireGuard, SSH). Use this as the default AEAD choice. .IP \(bu 4 \&\fBXChaCha20\-Poly1305\fR (Crypt::AuthEnc::XChaCha20Poly1305) \- Extended 24\-byte nonce variant. Prefer over ChaCha20\-Poly1305 when nonces are generated randomly. .IP \(bu 4 \&\fBAES\-GCM\fR (Crypt::AuthEnc::GCM) \- The standard AEAD mode for AES. Hardware\-accelerated on modern CPUs. Requires unique nonces; nonce reuse breaks the security entirely. .IP \(bu 4 \&\fBAES\-SIV\fR (Crypt::AuthEnc::SIV) \- Deterministic AEAD, nonce\-misuse resistant. Slightly slower but safer when nonce uniqueness cannot be guaranteed. .IP \(bu 4 \&\fBAES\-GCM\-SIV\fR (Crypt::AuthEnc::GCMSIV) \- Nonce\-misuse\-resistant AEAD (RFC 8452). Faster than AES\-SIV; pick this when you need GCM\-like performance with nonce\-reuse safety. .IP \(bu 4 \&\fBAES\-OCB\fR (Crypt::AuthEnc::OCB) \- Very fast single\-pass AEAD. Check patent status for your jurisdiction. .IP \(bu 4 \&\fBAES\-EAX\fR (Crypt::AuthEnc::EAX) \- Two\-pass AEAD based on CTR+OMAC. No patents, no nonce\-length restrictions. .IP \(bu 4 \&\fBAES\-CCM\fR (Crypt::AuthEnc::CCM) \- Used in WiFi (WPA2) and Bluetooth. Requires knowing the plaintext length in advance. .PP \fICryptographically Secure Randomness and UUIDs\fR .IX Subsection "Cryptographically Secure Randomness and UUIDs" .IP \(bu 4 \&\fBRandom bytes / strings\fR (Crypt::PRNG) \- Use this for salts, keys, nonces, tokens, and any other secret random values. The functional helpers \&\f(CW\*(C`random_bytes\*(C'\fR, \f(CW\*(C`random_bytes_hex\*(C'\fR, \f(CW\*(C`random_bytes_b64\*(C'\fR, \f(CW\*(C`random_bytes_b64u\*(C'\fR, \&\f(CW\*(C`random_string\*(C'\fR, and \f(CW\*(C`random_string_from\*(C'\fR 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. .IP \(bu 4 \&\fBUUIDs\fR ("random_v4uuid" in Crypt::Misc, "random_v7uuid" in Crypt::Misc) \- Use \f(CW\*(C`random_v4uuid\*(C'\fR for opaque random identifiers. Use \f(CW\*(C`random_v7uuid\*(C'\fR when you want roughly time\-ordered identifiers that sort by creation time at millisecond granularity. UUIDs are identifiers, not replacements for secret random bytes. .PP \fIStream Ciphers\fR .IX Subsection "Stream Ciphers" .PP 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. .IP \(bu 4 \&\fBChaCha\fR (Crypt::Stream::ChaCha) \- The default stream cipher choice. Same core as ChaCha20\-Poly1305 without the built\-in MAC. .IP \(bu 4 \&\fBXChaCha\fR (Crypt::Stream::XChaCha) \- Extended 24\-byte nonce variant of ChaCha. Prefer when nonces are generated randomly. .IP \(bu 4 \&\fBSalsa20\fR / \fBXSalsa20\fR (Crypt::Stream::Salsa20, Crypt::Stream::XSalsa20) \- Predecessor of ChaCha. Prefer ChaCha for new designs; Salsa20 only for interoperability (e.g. NaCl/libsodium). .IP \(bu 4 \&\fBRC4\fR (Crypt::Stream::RC4) \- \fBBroken; do not use for new designs.\fR Provided for legacy interoperability only. .IP \(bu 4 \&\fBRabbit\fR, \fBSober128\fR, \fBSosemanuk\fR (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. .PP \fIBlock Cipher Modes (without authentication)\fR .IX Subsection "Block Cipher Modes (without authentication)" .PP Use these only when authentication is handled separately or not needed: .IP \(bu 4 \&\fBCTR\fR (Crypt::Mode::CTR) \- Turns a block cipher into a stream cipher. Parallelizable. .IP \(bu 4 \&\fBCBC\fR (Crypt::Mode::CBC) \- Classic mode, needs padding. Prefer CTR or an AEAD mode. .IP \(bu 4 \&\fBXTS\fR (Crypt::Mode::XTS) \- For encrypting storage in place (disk sectors); one tweaked data unit per call. Not for data that travels. .IP \(bu 4 \&\fBECB\fR (Crypt::Mode::ECB) \- \fBInsecure for most uses.\fR Each block encrypted independently. .PP 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, \&\fBAES\fR is the default; it is hardware\-accelerated on most modern CPUs. .PP \fIHash Functions\fR .IX Subsection "Hash Functions" .IP \(bu 4 \&\fBSHA\-256\fR / \fBSHA\-384\fR / \fBSHA\-512\fR (Crypt::Digest::SHA256, etc.) \- The default choice for general hashing. Widely supported and well analyzed. .IP \(bu 4 \&\fBSHA3\-256\fR / \fBSHA3\-512\fR (Crypt::Digest::SHA3_256, etc.) \- Alternative to SHA\-2 with a completely different construction (Keccak sponge). .IP \(bu 4 \&\fBBLAKE2b\fR / \fBBLAKE2s\fR (Crypt::Digest::BLAKE2b_256, etc.) \- Very fast, especially in software. BLAKE2b for 64\-bit platforms, BLAKE2s for 32\-bit. .IP \(bu 4 \&\fBSHAKE\fR / \fBTurboSHAKE\fR / \fBKangarooTwelve\fR \- Extendable\-output functions (XOFs). Use when you need variable\-length output. .PP \fIChecksums\fR .IX Subsection "Checksums" .PP 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. .PP \fIMessage Authentication Codes\fR .IX Subsection "Message Authentication Codes" .IP \(bu 4 \&\fBHMAC\fR (Crypt::Mac::HMAC) \- The standard MAC construction. Works with any hash. Use HMAC\-SHA256 as the default. .IP \(bu 4 \&\fBPoly1305\fR (Crypt::Mac::Poly1305) \- One\-time MAC, very fast. Used as part of ChaCha20\-Poly1305. Requires a unique key per message. .IP \(bu 4 \&\fBBLAKE2b\-MAC\fR (Crypt::Mac::BLAKE2b) \- Keyed BLAKE2. Faster than HMAC\-SHA256 in software. .IP \(bu 4 \&\fBCMAC/OMAC\fR (Crypt::Mac::OMAC) \- Block\-cipher\-based MAC. Use when you already have AES but not a hash function. .PP \fIPublic\-Key Cryptography\fR .IX Subsection "Public-Key Cryptography" .IP \(bu 4 \&\fBEd25519\fR (Crypt::PK::Ed25519) \- Modern digital signatures. Fast, constant\-time, small keys/signatures. The default choice for new signature schemes. .IP \(bu 4 \&\fBEd448\fR (Crypt::PK::Ed448) \- Higher security margin than Ed25519 (~224\-bit vs ~128\-bit). .IP \(bu 4 \&\fBX25519\fR (Crypt::PK::X25519) \- Elliptic\-curve Diffie\-Hellman key agreement. The default choice for key exchange. .IP \(bu 4 \&\fBX448\fR (Crypt::PK::X448) \- Higher security margin than X25519. .IP \(bu 4 \&\fBECDSA\fR (Crypt::PK::ECC) \- Widely used (TLS, Bitcoin). Prefer Ed25519 for new designs unless ECDSA is required for interoperability. .IP \(bu 4 \&\fBRSA\fR (Crypt::PK::RSA) \- Legacy but very widely used. Use 2048\-bit keys minimum, 4096\-bit preferred. Prefer OAEP for encryption and PSS for signatures. .IP \(bu 4 \&\fBDSA\fR (Crypt::PK::DSA) \- Legacy. Prefer Ed25519 or ECDSA. .IP \(bu 4 \&\fBDH\fR (Crypt::PK::DH) \- Classic Diffie\-Hellman. Prefer X25519 for new designs. .PP \fIKey Derivation / Password hashing\fR .IX Subsection "Key Derivation / Password hashing" .IP \(bu 4 \&\fBHKDF\fR ("hkdf" in Crypt::KeyDerivation) \- Extract\-then\-expand KDF. Use for deriving keys from shared secrets (e.g. after ECDH). .IP \(bu 4 \&\fBArgon2\fR ("argon2_pbkdf" in Crypt::KeyDerivation) \- Memory\-hard password hashing. The recommended choice for password storage. .IP \(bu 4 \&\fBBcrypt\fR ("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. .IP \(bu 4 \&\fBScrypt\fR ("scrypt_pbkdf" in Crypt::KeyDerivation) \- Memory\-hard KDF. Use Argon2 if available. .IP \(bu 4 \&\fBPBKDF2\fR ("pbkdf2" in Crypt::KeyDerivation) \- Widely supported but CPU\-only hardness. Use Argon2 or Scrypt when possible. .IP \(bu 4 \&\fBPBKDF1\fR ("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. .SS "Error Handling" .IX Subsection "Error Handling" Most CryptX modules report errors by calling \f(CW\*(C`croak\*(C'\fR (from Carp). Invalid parameters, unsupported algorithms, wrong key sizes, malformed input, and internal library failures usually croak with a descriptive message. Catch exceptions with \f(CW\*(C`eval\*(C'\fR or Try::Tiny. .PP Some validation\-style helpers use a return value instead of croaking. The most important examples are the \f(CW*_decrypt_verify\fR functions in the authenticated encryption modules \f(CW\*(C`Crypt::AuthEnc::*\*(C'\fR. These return \f(CW\*(C`undef\*(C'\fR 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 \f(CW\*(C`undef\*(C'\fR or false for malformed input, so check the concrete module POD when you need exact failure semantics. .SS "Module Map" .IX Subsection "Module Map" .IP \(bu 4 Top\-level family modules .Sp Crypt::Cipher, Crypt::Mode, Crypt::AuthEnc, Crypt::Digest, Crypt::Mac, Crypt::Checksum, Crypt::PRNG, Crypt::PK, Crypt::KeyDerivation, Crypt::Misc, Crypt::ASN1 .IP \(bu 4 Symmetric ciphers .Sp Crypt::Cipher::AES, Crypt::Cipher::Anubis, Crypt::Cipher::ARIA, 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 .IP \(bu 4 Block cipher modes .Sp Crypt::Mode::CBC, Crypt::Mode::CFB, Crypt::Mode::CTR, Crypt::Mode::ECB, Crypt::Mode::OFB, Crypt::Mode::XTS .IP \(bu 4 Stream ciphers .Sp Crypt::Stream::RC4, Crypt::Stream::ChaCha, Crypt::Stream::XChaCha, Crypt::Stream::Salsa20, Crypt::Stream::XSalsa20, Crypt::Stream::Sober128, Crypt::Stream::Sosemanuk, Crypt::Stream::Rabbit .IP \(bu 4 Authenticated encryption modes .Sp Crypt::AuthEnc::CCM, Crypt::AuthEnc::EAX, Crypt::AuthEnc::GCM, Crypt::AuthEnc::GCMSIV, Crypt::AuthEnc::OCB, Crypt::AuthEnc::ChaCha20Poly1305, Crypt::AuthEnc::XChaCha20Poly1305, Crypt::AuthEnc::SIV .IP \(bu 4 Hash functions .Sp 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::BLAKE3, 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, Crypt::Digest::SM3 .IP \(bu 4 Checksums .Sp Crypt::Checksum::Adler32, Crypt::Checksum::CRC32 .IP \(bu 4 Message authentication codes .Sp Crypt::Mac::BLAKE2b, Crypt::Mac::BLAKE2s, Crypt::Mac::F9, Crypt::Mac::HMAC, Crypt::Mac::KMAC, Crypt::Mac::OMAC, Crypt::Mac::Pelican, Crypt::Mac::PMAC, Crypt::Mac::XCBC, Crypt::Mac::Poly1305 .IP \(bu 4 Public\-key cryptography .Sp Crypt::PK::RSA, Crypt::PK::DSA, Crypt::PK::ECC, Crypt::PK::DH, Crypt::PK::Ed25519, Crypt::PK::X25519, Crypt::PK::Ed448, Crypt::PK::X448 .IP \(bu 4 Cryptographically secure random number generators .Sp Crypt::PRNG::Fortuna, Crypt::PRNG::Yarrow, Crypt::PRNG::RC4, Crypt::PRNG::Sober128, Crypt::PRNG::ChaCha20 .IP \(bu 4 Key derivation functions .Sp Crypt::KeyDerivation .IP \(bu 4 ASN.1 parser .Sp Crypt::ASN1 .Sp Use \f(CW\*(C`Crypt::ASN1\*(C'\fR only when you need custom ASN.1 / DER parsing or encoding. Most common key and certificate formats are already handled by the PK modules. .IP \(bu 4 Miscellaneous helpers .Sp Crypt::Misc (base64/base32/base58 codecs, PEM helpers, constant\-time compare, UUID generation, octet increment helpers, and related utility functions) .SS "Diagnostic Functions" .IX Subsection "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. .PP \fIltc_build_settings\fR .IX Subsection "ltc_build_settings" .PP .Vb 1 \& my $str = CryptX::ltc_build_settings(); .Ve .PP 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.). .PP \fIltc_mp_name\fR .IX Subsection "ltc_mp_name" .PP .Vb 2 \& my $name = CryptX::ltc_mp_name(); \& # e.g. "LTM" (LibTomMath) .Ve .PP Returns the name of the math provider back\-end in use. .PP \fIltc_mp_bits_per_digit\fR .IX Subsection "ltc_mp_bits_per_digit" .PP .Vb 2 \& my $bits = CryptX::ltc_mp_bits_per_digit(); \& # e.g. 60 .Ve .PP Returns the number of bits per digit used by the math provider. .SS "Math::BigInt backend" .IX Subsection "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. .SH LICENSE .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright (c) 2013\-2026 DCIT, a.s. / Karel Miko