| 1 | package CryptX; | ||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||
| 3 | 160 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 4 | 160 | ▶ | use warnings ; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 5 | 160 | our $VERSION = '0.091'; | |||||||||||||||||||||||||||
| 6 | |||||||||||||||||||||||||||||
| 7 | 160 | require XSLoader; | |||||||||||||||||||||||||||
| 8 | 160 | XSLoader::load('CryptX', $VERSION); | |||||||||||||||||||||||||||
| 9 | |||||||||||||||||||||||||||||
| 10 | 160 | ▶ | use Carp; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 11 | 160 | my $has_json; | |||||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||||||
| 13 | 160 | ▶ | BEGIN { | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=2 SCAR=8.1
| |||||||||||||||||||||||||||||
| 14 | 0 | ▶ | $has_json = 1 if eval { require JSON; 1 }; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 15 | } | ||||||||||||||||||||||||||||
| 16 | |||||||||||||||||||||||||||||
| 17 | 49 | ▶ | sub _croak { | ||||||||||||||||||||||||||
|
Subroutine
_croak: called CC=4 SCAR=15.2
| |||||||||||||||||||||||||||||
| 18 | 49 | ▶ | die @_ if ref $_[0] || !$_[-1]; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
ref $_[0] or not $_[-1]
MC/DC0%0/2
ref $_[0] or not $_[-1]
ref $_[0]
not $_[-1]
Truth table33%1/3
A or not(B)
A= ref $_[0]B= not $_[-1]
| |||||||||||||||||||||||||||||
| 19 | 49 | ▶ | if ($_[-1] =~ /^(.*)( at .+ line .+\n$)/s) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 20 | 49 | pop @_; | |||||||||||||||||||||||||||
| 21 | 49 | push @_, $1; | |||||||||||||||||||||||||||
| 22 | } | ||||||||||||||||||||||||||||
| 23 | 49 | die Carp::shortmess @_; | |||||||||||||||||||||||||||
| 24 | } | ||||||||||||||||||||||||||||
| 25 | |||||||||||||||||||||||||||||
| 26 | 0 | ▶ | sub _decode_json { | ||||||||||||||||||||||||||
|
Subroutine
_decode_json: not called CC=2 SCAR=17.9
| |||||||||||||||||||||||||||||
| 27 | 0 | ▶ | croak "FATAL: cannot find JSON module" if !$has_json; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 28 | 0 | return JSON->new->utf8->decode(shift); | |||||||||||||||||||||||||||
| 29 | } | ||||||||||||||||||||||||||||
| 30 | |||||||||||||||||||||||||||||
| 31 | 0 | ▶ | sub _encode_json { | ||||||||||||||||||||||||||
|
Subroutine
_encode_json: not called CC=2 SCAR=17.9
| |||||||||||||||||||||||||||||
| 32 | 0 | ▶ | croak "FATAL: cannot find JSON module" if !$has_json; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 33 | 0 | return JSON->new->utf8->canonical->encode(shift); | |||||||||||||||||||||||||||
| 34 | } | ||||||||||||||||||||||||||||
| 35 | |||||||||||||||||||||||||||||
| 36 | 160 | 1; | |||||||||||||||||||||||||||
| 37 | |||||||||||||||||||||||||||||
| 38 | =pod | ||||||||||||||||||||||||||||
| 39 | |||||||||||||||||||||||||||||
| 40 | =head1 NAME | ||||||||||||||||||||||||||||
| 41 | |||||||||||||||||||||||||||||
| 42 | CryptX - Cryptographic toolkit | ||||||||||||||||||||||||||||
| 43 | |||||||||||||||||||||||||||||
| 44 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 45 | |||||||||||||||||||||||||||||
| 46 | CryptX is the distribution entry point. In normal code, load one of the concrete modules listed below. | ||||||||||||||||||||||||||||
| 47 | |||||||||||||||||||||||||||||
| 48 | ## one-shot hashing | ||||||||||||||||||||||||||||
| 49 | use Crypt::Digest qw(digest_data_hex); | ||||||||||||||||||||||||||||
| 50 | my $sha256 = digest_data_hex('SHA256', 'hello world'); | ||||||||||||||||||||||||||||
| 51 | |||||||||||||||||||||||||||||
| 52 | ## classic AES-CBC encryption with padding | ||||||||||||||||||||||||||||
| 53 | use Crypt::Mode::CBC; | ||||||||||||||||||||||||||||
| 54 | my $cbc = Crypt::Mode::CBC->new('AES'); | ||||||||||||||||||||||||||||
| 55 | my $iv = random_bytes(16); # 16-byte AES block-size IV | ||||||||||||||||||||||||||||
| 56 | my $cbc_ciphertext = $cbc->encrypt('hello world', $key, $iv); | ||||||||||||||||||||||||||||
| 57 | |||||||||||||||||||||||||||||
| 58 | ## authenticated encryption (AEAD) with AES | ||||||||||||||||||||||||||||
| 59 | use Crypt::AuthEnc::GCM qw(gcm_encrypt_authenticate); | ||||||||||||||||||||||||||||
| 60 | my $key = random_bytes(32); # 32-byte AES-256 key | ||||||||||||||||||||||||||||
| 61 | my $nonce = random_bytes(12); # 12-byte unique nonce | ||||||||||||||||||||||||||||
| 62 | my ($ciphertext, $tag) = gcm_encrypt_authenticate('AES', $key, $nonce, 'header', 'hello world'); | ||||||||||||||||||||||||||||
| 63 | |||||||||||||||||||||||||||||
| 64 | ## message authentication | ||||||||||||||||||||||||||||
| 65 | use Crypt::Mac::HMAC qw(hmac_hex); | ||||||||||||||||||||||||||||
| 66 | my $mac = hmac_hex('SHA256', $key, 'hello world'); | ||||||||||||||||||||||||||||
| 67 | |||||||||||||||||||||||||||||
| 68 | ## secure random data + UUID helpers | ||||||||||||||||||||||||||||
| 69 | use Crypt::PRNG qw(random_bytes random_string); | ||||||||||||||||||||||||||||
| 70 | use Crypt::Misc qw(random_v4uuid random_v7uuid); | ||||||||||||||||||||||||||||
| 71 | my $salt = random_bytes(16); | ||||||||||||||||||||||||||||
| 72 | my $token = random_string(24); | ||||||||||||||||||||||||||||
| 73 | my $uuid4 = random_v4uuid(); | ||||||||||||||||||||||||||||
| 74 | my $uuid7 = random_v7uuid(); | ||||||||||||||||||||||||||||
| 75 | |||||||||||||||||||||||||||||
| 76 | ## classic password-based key derivation | ||||||||||||||||||||||||||||
| 77 | use Crypt::KeyDerivation qw(pbkdf2); | ||||||||||||||||||||||||||||
| 78 | my $dk = pbkdf2('password', $salt, 100_000, 'SHA256', 32); | ||||||||||||||||||||||||||||
| 79 | |||||||||||||||||||||||||||||
| 80 | ## bare stream cipher (authenticate separately) | ||||||||||||||||||||||||||||
| 81 | use Crypt::Stream::ChaCha; | ||||||||||||||||||||||||||||
| 82 | my $stream = Crypt::Stream::ChaCha->new($key, $nonce); | ||||||||||||||||||||||||||||
| 83 | my $stream_ciphertext = $stream->crypt('hello world'); | ||||||||||||||||||||||||||||
| 84 | |||||||||||||||||||||||||||||
| 85 | ## modern signatures | ||||||||||||||||||||||||||||
| 86 | use Crypt::PK::Ed25519; | ||||||||||||||||||||||||||||
| 87 | my $signer = Crypt::PK::Ed25519->new->generate_key; | ||||||||||||||||||||||||||||
| 88 | my $sig = $signer->sign_message('hello world'); | ||||||||||||||||||||||||||||
| 89 | my $ok = $signer->verify_message($sig, 'hello world'); | ||||||||||||||||||||||||||||
| 90 | |||||||||||||||||||||||||||||
| 91 | ## key agreement | ||||||||||||||||||||||||||||
| 92 | use Crypt::PK::X25519; | ||||||||||||||||||||||||||||
| 93 | my $alice = Crypt::PK::X25519->new->generate_key; | ||||||||||||||||||||||||||||
| 94 | my $bob = Crypt::PK::X25519->new->generate_key; | ||||||||||||||||||||||||||||
| 95 | my $shared_secret = $alice->shared_secret($bob); | ||||||||||||||||||||||||||||
| 96 | |||||||||||||||||||||||||||||
| 97 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||
| 98 | |||||||||||||||||||||||||||||
| 99 | Perl cryptographic modules built on the bundled L<LibTomCrypt|https://github.com/libtom/libtomcrypt> library. | ||||||||||||||||||||||||||||
| 100 | The distribution also includes L<Math::BigInt::LTM>, a L<Math::BigInt> backend | ||||||||||||||||||||||||||||
| 101 | built on the bundled L<LibTomMath|https://www.libtom.net/LibTomMath/> library | ||||||||||||||||||||||||||||
| 102 | used internally by LibTomCrypt. | ||||||||||||||||||||||||||||
| 103 | |||||||||||||||||||||||||||||
| 104 | This module mainly serves as the top-level distribution/documentation page. For actual work, | ||||||||||||||||||||||||||||
| 105 | use one of the concrete modules listed below. | ||||||||||||||||||||||||||||
| 106 | |||||||||||||||||||||||||||||
| 107 | =head2 Algorithm Selection Guide | ||||||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||||
| 109 | =head3 Authenticated Encryption (AEAD) | ||||||||||||||||||||||||||||
| 110 | |||||||||||||||||||||||||||||
| 111 | For new designs, prefer authenticated encryption (AEAD) over bare cipher modes: | ||||||||||||||||||||||||||||
| 112 | |||||||||||||||||||||||||||||
| 113 | =over | ||||||||||||||||||||||||||||
| 114 | |||||||||||||||||||||||||||||
| 115 | =item * B<ChaCha20-Poly1305> (L<Crypt::AuthEnc::ChaCha20Poly1305>) - Fast, constant-time, | ||||||||||||||||||||||||||||
| 116 | widely deployed (TLS 1.3, WireGuard, SSH). Use this as the default AEAD choice. | ||||||||||||||||||||||||||||
| 117 | |||||||||||||||||||||||||||||
| 118 | =item * B<XChaCha20-Poly1305> (L<Crypt::AuthEnc::XChaCha20Poly1305>) - Extended 24-byte nonce | ||||||||||||||||||||||||||||
| 119 | variant. Prefer over ChaCha20-Poly1305 when nonces are generated randomly. | ||||||||||||||||||||||||||||
| 120 | |||||||||||||||||||||||||||||
| 121 | =item * B<AES-GCM> (L<Crypt::AuthEnc::GCM>) - The standard AEAD mode for AES. Hardware-accelerated | ||||||||||||||||||||||||||||
| 122 | on modern CPUs. Requires unique nonces; nonce reuse breaks the security entirely. | ||||||||||||||||||||||||||||
| 123 | |||||||||||||||||||||||||||||
| 124 | =item * B<AES-SIV> (L<Crypt::AuthEnc::SIV>) - Deterministic AEAD, nonce-misuse resistant. | ||||||||||||||||||||||||||||
| 125 | Slightly slower but safer when nonce uniqueness cannot be guaranteed. | ||||||||||||||||||||||||||||
| 126 | |||||||||||||||||||||||||||||
| 127 | =item * B<AES-GCM-SIV> (L<Crypt::AuthEnc::GCMSIV>) - Nonce-misuse-resistant AEAD (RFC 8452). | ||||||||||||||||||||||||||||
| 128 | Faster than AES-SIV; pick this when you need GCM-like performance with nonce-reuse safety. | ||||||||||||||||||||||||||||
| 129 | |||||||||||||||||||||||||||||
| 130 | =item * B<AES-OCB> (L<Crypt::AuthEnc::OCB>) - Very fast single-pass AEAD. Check patent status | ||||||||||||||||||||||||||||
| 131 | for your jurisdiction. | ||||||||||||||||||||||||||||
| 132 | |||||||||||||||||||||||||||||
| 133 | =item * B<AES-EAX> (L<Crypt::AuthEnc::EAX>) - Two-pass AEAD based on CTR+OMAC. No patents, | ||||||||||||||||||||||||||||
| 134 | no nonce-length restrictions. | ||||||||||||||||||||||||||||
| 135 | |||||||||||||||||||||||||||||
| 136 | =item * B<AES-CCM> (L<Crypt::AuthEnc::CCM>) - Used in WiFi (WPA2) and Bluetooth. Requires | ||||||||||||||||||||||||||||
| 137 | knowing the plaintext length in advance. | ||||||||||||||||||||||||||||
| 138 | |||||||||||||||||||||||||||||
| 139 | =back | ||||||||||||||||||||||||||||
| 140 | |||||||||||||||||||||||||||||
| 141 | =head3 Cryptographically Secure Randomness and UUIDs | ||||||||||||||||||||||||||||
| 142 | |||||||||||||||||||||||||||||
| 143 | =over | ||||||||||||||||||||||||||||
| 144 | |||||||||||||||||||||||||||||
| 145 | =item * B<Random bytes / strings> (L<Crypt::PRNG>) - Use this for salts, keys, nonces, tokens, | ||||||||||||||||||||||||||||
| 146 | and any other secret random values. The functional helpers | ||||||||||||||||||||||||||||
| 147 | C<random_bytes>, C<random_bytes_hex>, C<random_bytes_b64>, C<random_bytes_b64u>, | ||||||||||||||||||||||||||||
| 148 | C<random_string>, and C<random_string_from> cover most use cases. The OO API | ||||||||||||||||||||||||||||
| 149 | and the algorithm-specific wrappers (L<Crypt::PRNG::ChaCha20>, L<Crypt::PRNG::Fortuna>, etc.) | ||||||||||||||||||||||||||||
| 150 | are mainly for deterministic streams or interoperability with a specific PRNG. | ||||||||||||||||||||||||||||
| 151 | |||||||||||||||||||||||||||||
| 152 | =item * B<UUIDs> (L<Crypt::Misc/random_v4uuid>, L<Crypt::Misc/random_v7uuid>) - Use C<random_v4uuid> | ||||||||||||||||||||||||||||
| 153 | for opaque random identifiers. Use C<random_v7uuid> when you want roughly time-ordered identifiers | ||||||||||||||||||||||||||||
| 154 | that sort by creation time at millisecond granularity. UUIDs are identifiers, not replacements for | ||||||||||||||||||||||||||||
| 155 | secret random bytes. | ||||||||||||||||||||||||||||
| 156 | |||||||||||||||||||||||||||||
| 157 | =back | ||||||||||||||||||||||||||||
| 158 | |||||||||||||||||||||||||||||
| 159 | =head3 Stream Ciphers | ||||||||||||||||||||||||||||
| 160 | |||||||||||||||||||||||||||||
| 161 | Stream ciphers encrypt data byte-by-byte without block padding. For most | ||||||||||||||||||||||||||||
| 162 | applications prefer an AEAD mode (see above) which bundles encryption with | ||||||||||||||||||||||||||||
| 163 | authentication. Use bare stream ciphers only when you handle authentication | ||||||||||||||||||||||||||||
| 164 | separately. | ||||||||||||||||||||||||||||
| 165 | |||||||||||||||||||||||||||||
| 166 | =over | ||||||||||||||||||||||||||||
| 167 | |||||||||||||||||||||||||||||
| 168 | =item * B<ChaCha> (L<Crypt::Stream::ChaCha>) - The default stream cipher choice. | ||||||||||||||||||||||||||||
| 169 | Same core as ChaCha20-Poly1305 without the built-in MAC. | ||||||||||||||||||||||||||||
| 170 | |||||||||||||||||||||||||||||
| 171 | =item * B<XChaCha> (L<Crypt::Stream::XChaCha>) - Extended 24-byte nonce variant of ChaCha. | ||||||||||||||||||||||||||||
| 172 | Prefer when nonces are generated randomly. | ||||||||||||||||||||||||||||
| 173 | |||||||||||||||||||||||||||||
| 174 | =item * B<Salsa20> / B<XSalsa20> (L<Crypt::Stream::Salsa20>, L<Crypt::Stream::XSalsa20>) - | ||||||||||||||||||||||||||||
| 175 | Predecessor of ChaCha. Prefer ChaCha for new designs; Salsa20 only for | ||||||||||||||||||||||||||||
| 176 | interoperability (e.g. NaCl/libsodium). | ||||||||||||||||||||||||||||
| 177 | |||||||||||||||||||||||||||||
| 178 | =item * B<RC4> (L<Crypt::Stream::RC4>) - B<Broken; do not use for new designs.> Provided for | ||||||||||||||||||||||||||||
| 179 | legacy interoperability only. | ||||||||||||||||||||||||||||
| 180 | |||||||||||||||||||||||||||||
| 181 | =item * B<Rabbit>, B<Sober128>, B<Sosemanuk> (L<Crypt::Stream::Rabbit>, L<Crypt::Stream::Sober128>, L<Crypt::Stream::Sosemanuk>) - | ||||||||||||||||||||||||||||
| 182 | Niche ciphers from the eSTREAM portfolio. Use ChaCha unless a specific protocol requires one of these. | ||||||||||||||||||||||||||||
| 183 | |||||||||||||||||||||||||||||
| 184 | =back | ||||||||||||||||||||||||||||
| 185 | |||||||||||||||||||||||||||||
| 186 | =head3 Block Cipher Modes (without authentication) | ||||||||||||||||||||||||||||
| 187 | |||||||||||||||||||||||||||||
| 188 | Use these only when authentication is handled separately or not needed: | ||||||||||||||||||||||||||||
| 189 | |||||||||||||||||||||||||||||
| 190 | =over | ||||||||||||||||||||||||||||
| 191 | |||||||||||||||||||||||||||||
| 192 | =item * B<CTR> (L<Crypt::Mode::CTR>) - Turns a block cipher into a stream cipher. Parallelizable. | ||||||||||||||||||||||||||||
| 193 | |||||||||||||||||||||||||||||
| 194 | =item * B<CBC> (L<Crypt::Mode::CBC>) - Classic mode, needs padding. Prefer CTR or an AEAD mode. | ||||||||||||||||||||||||||||
| 195 | |||||||||||||||||||||||||||||
| 196 | =item * B<XTS> (L<Crypt::Mode::XTS>) - For encrypting storage in place (disk sectors); one tweaked | ||||||||||||||||||||||||||||
| 197 | data unit per call. Not for data that travels. | ||||||||||||||||||||||||||||
| 198 | |||||||||||||||||||||||||||||
| 199 | =item * B<ECB> (L<Crypt::Mode::ECB>) - B<Insecure for most uses.> Each block encrypted independently. | ||||||||||||||||||||||||||||
| 200 | |||||||||||||||||||||||||||||
| 201 | =back | ||||||||||||||||||||||||||||
| 202 | |||||||||||||||||||||||||||||
| 203 | The individual L<Crypt::Cipher::AES>, L<Crypt::Cipher::Twofish>, etc. modules implement | ||||||||||||||||||||||||||||
| 204 | raw single-block encryption and are rarely used directly. In almost all cases you should | ||||||||||||||||||||||||||||
| 205 | use them through an AEAD mode (L<Crypt::AuthEnc::GCM>, L<Crypt::AuthEnc::CCM>) or a block | ||||||||||||||||||||||||||||
| 206 | cipher mode (L<Crypt::Mode::CBC>, L<Crypt::Mode::CTR>) instead. When choosing a cipher, | ||||||||||||||||||||||||||||
| 207 | B<AES> is the default; it is hardware-accelerated on most modern CPUs. | ||||||||||||||||||||||||||||
| 208 | |||||||||||||||||||||||||||||
| 209 | =head3 Hash Functions | ||||||||||||||||||||||||||||
| 210 | |||||||||||||||||||||||||||||
| 211 | =over | ||||||||||||||||||||||||||||
| 212 | |||||||||||||||||||||||||||||
| 213 | =item * B<SHA-256> / B<SHA-384> / B<SHA-512> (L<Crypt::Digest::SHA256>, etc.) - The default | ||||||||||||||||||||||||||||
| 214 | choice for general hashing. Widely supported and well analyzed. | ||||||||||||||||||||||||||||
| 215 | |||||||||||||||||||||||||||||
| 216 | =item * B<SHA3-256> / B<SHA3-512> (L<Crypt::Digest::SHA3_256>, etc.) - Alternative to SHA-2 | ||||||||||||||||||||||||||||
| 217 | with a completely different construction (Keccak sponge). | ||||||||||||||||||||||||||||
| 218 | |||||||||||||||||||||||||||||
| 219 | =item * B<BLAKE2b> / B<BLAKE2s> (L<Crypt::Digest::BLAKE2b_256>, etc.) - Very fast, especially | ||||||||||||||||||||||||||||
| 220 | in software. BLAKE2b for 64-bit platforms, BLAKE2s for 32-bit. | ||||||||||||||||||||||||||||
| 221 | |||||||||||||||||||||||||||||
| 222 | =item * B<SHAKE> / B<TurboSHAKE> / B<KangarooTwelve> - Extendable-output functions (XOFs). | ||||||||||||||||||||||||||||
| 223 | Use when you need variable-length output. | ||||||||||||||||||||||||||||
| 224 | |||||||||||||||||||||||||||||
| 225 | =back | ||||||||||||||||||||||||||||
| 226 | |||||||||||||||||||||||||||||
| 227 | =head3 Checksums | ||||||||||||||||||||||||||||
| 228 | |||||||||||||||||||||||||||||
| 229 | Use L<Crypt::Checksum::CRC32> and L<Crypt::Checksum::Adler32> only for | ||||||||||||||||||||||||||||
| 230 | non-adversarial integrity checks such as accidental corruption detection. | ||||||||||||||||||||||||||||
| 231 | They are not cryptographic integrity or authenticity mechanisms. For | ||||||||||||||||||||||||||||
| 232 | cryptographic use, prefer L<Crypt::Digest>, L<Crypt::Mac>, or an AEAD mode | ||||||||||||||||||||||||||||
| 233 | from L<Crypt::AuthEnc>. | ||||||||||||||||||||||||||||
| 234 | |||||||||||||||||||||||||||||
| 235 | =head3 Message Authentication Codes | ||||||||||||||||||||||||||||
| 236 | |||||||||||||||||||||||||||||
| 237 | =over | ||||||||||||||||||||||||||||
| 238 | |||||||||||||||||||||||||||||
| 239 | =item * B<HMAC> (L<Crypt::Mac::HMAC>) - The standard MAC construction. Works with any hash. | ||||||||||||||||||||||||||||
| 240 | Use HMAC-SHA256 as the default. | ||||||||||||||||||||||||||||
| 241 | |||||||||||||||||||||||||||||
| 242 | =item * B<Poly1305> (L<Crypt::Mac::Poly1305>) - One-time MAC, very fast. Used as part of | ||||||||||||||||||||||||||||
| 243 | ChaCha20-Poly1305. Requires a unique key per message. | ||||||||||||||||||||||||||||
| 244 | |||||||||||||||||||||||||||||
| 245 | =item * B<BLAKE2b-MAC> (L<Crypt::Mac::BLAKE2b>) - Keyed BLAKE2. Faster than HMAC-SHA256 in | ||||||||||||||||||||||||||||
| 246 | software. | ||||||||||||||||||||||||||||
| 247 | |||||||||||||||||||||||||||||
| 248 | =item * B<CMAC/OMAC> (L<Crypt::Mac::OMAC>) - Block-cipher-based MAC. Use when you already | ||||||||||||||||||||||||||||
| 249 | have AES but not a hash function. | ||||||||||||||||||||||||||||
| 250 | |||||||||||||||||||||||||||||
| 251 | =back | ||||||||||||||||||||||||||||
| 252 | |||||||||||||||||||||||||||||
| 253 | =head3 Public-Key Cryptography | ||||||||||||||||||||||||||||
| 254 | |||||||||||||||||||||||||||||
| 255 | =over | ||||||||||||||||||||||||||||
| 256 | |||||||||||||||||||||||||||||
| 257 | =item * B<Ed25519> (L<Crypt::PK::Ed25519>) - Modern digital signatures. Fast, constant-time, | ||||||||||||||||||||||||||||
| 258 | small keys/signatures. The default choice for new signature schemes. | ||||||||||||||||||||||||||||
| 259 | |||||||||||||||||||||||||||||
| 260 | =item * B<Ed448> (L<Crypt::PK::Ed448>) - Higher security margin than Ed25519 (~224-bit vs ~128-bit). | ||||||||||||||||||||||||||||
| 261 | |||||||||||||||||||||||||||||
| 262 | =item * B<X25519> (L<Crypt::PK::X25519>) - Elliptic-curve Diffie-Hellman key agreement. The | ||||||||||||||||||||||||||||
| 263 | default choice for key exchange. | ||||||||||||||||||||||||||||
| 264 | |||||||||||||||||||||||||||||
| 265 | =item * B<X448> (L<Crypt::PK::X448>) - Higher security margin than X25519. | ||||||||||||||||||||||||||||
| 266 | |||||||||||||||||||||||||||||
| 267 | =item * B<ECDSA> (L<Crypt::PK::ECC>) - Widely used (TLS, Bitcoin). Prefer Ed25519 for new | ||||||||||||||||||||||||||||
| 268 | designs unless ECDSA is required for interoperability. | ||||||||||||||||||||||||||||
| 269 | |||||||||||||||||||||||||||||
| 270 | =item * B<RSA> (L<Crypt::PK::RSA>) - Legacy but very widely used. Use 2048-bit keys minimum, 4096-bit | ||||||||||||||||||||||||||||
| 271 | preferred. Prefer OAEP for encryption and PSS for signatures. | ||||||||||||||||||||||||||||
| 272 | |||||||||||||||||||||||||||||
| 273 | =item * B<DSA> (L<Crypt::PK::DSA>) - Legacy. Prefer Ed25519 or ECDSA. | ||||||||||||||||||||||||||||
| 274 | |||||||||||||||||||||||||||||
| 275 | =item * B<DH> (L<Crypt::PK::DH>) - Classic Diffie-Hellman. Prefer X25519 for new designs. | ||||||||||||||||||||||||||||
| 276 | |||||||||||||||||||||||||||||
| 277 | =back | ||||||||||||||||||||||||||||
| 278 | |||||||||||||||||||||||||||||
| 279 | =head3 Key Derivation / Password hashing | ||||||||||||||||||||||||||||
| 280 | |||||||||||||||||||||||||||||
| 281 | =over | ||||||||||||||||||||||||||||
| 282 | |||||||||||||||||||||||||||||
| 283 | =item * B<HKDF> (L<Crypt::KeyDerivation/hkdf>) - Extract-then-expand KDF. Use for deriving | ||||||||||||||||||||||||||||
| 284 | keys from shared secrets (e.g. after ECDH). | ||||||||||||||||||||||||||||
| 285 | |||||||||||||||||||||||||||||
| 286 | =item * B<Argon2> (L<Crypt::KeyDerivation/argon2_pbkdf>) - Memory-hard password hashing. The | ||||||||||||||||||||||||||||
| 287 | recommended choice for password storage. | ||||||||||||||||||||||||||||
| 288 | |||||||||||||||||||||||||||||
| 289 | =item * B<Bcrypt> (L<Crypt::KeyDerivation/bcrypt_pbkdf>) - Use mainly for compatibility | ||||||||||||||||||||||||||||
| 290 | with formats and protocols that specifically require bcrypt-based key derivation (for example | ||||||||||||||||||||||||||||
| 291 | some OpenSSH workflows). Prefer Argon2 for new password-storage designs. | ||||||||||||||||||||||||||||
| 292 | |||||||||||||||||||||||||||||
| 293 | =item * B<Scrypt> (L<Crypt::KeyDerivation/scrypt_pbkdf>) - Memory-hard KDF. Use Argon2 if available. | ||||||||||||||||||||||||||||
| 294 | |||||||||||||||||||||||||||||
| 295 | =item * B<PBKDF2> (L<Crypt::KeyDerivation/pbkdf2>) - Widely supported but CPU-only hardness. | ||||||||||||||||||||||||||||
| 296 | Use Argon2 or Scrypt when possible. | ||||||||||||||||||||||||||||
| 297 | |||||||||||||||||||||||||||||
| 298 | =item * B<PBKDF1> (L<Crypt::KeyDerivation/pbkdf1>, L<Crypt::KeyDerivation/pbkdf1_openssl>) - Legacy | ||||||||||||||||||||||||||||
| 299 | derivation only. Keep this for interoperability with older formats; do not use it for new designs. | ||||||||||||||||||||||||||||
| 300 | |||||||||||||||||||||||||||||
| 301 | =back | ||||||||||||||||||||||||||||
| 302 | |||||||||||||||||||||||||||||
| 303 | =head2 Error Handling | ||||||||||||||||||||||||||||
| 304 | |||||||||||||||||||||||||||||
| 305 | Most CryptX modules report errors by calling C<croak> (from L<Carp>). | ||||||||||||||||||||||||||||
| 306 | Invalid parameters, unsupported algorithms, wrong key sizes, malformed | ||||||||||||||||||||||||||||
| 307 | input, and internal library failures usually croak with a descriptive | ||||||||||||||||||||||||||||
| 308 | message. Catch exceptions with C<eval> or L<Try::Tiny>. | ||||||||||||||||||||||||||||
| 309 | |||||||||||||||||||||||||||||
| 310 | Some validation-style helpers use a return value instead of croaking. The | ||||||||||||||||||||||||||||
| 311 | most important examples are the C<*_decrypt_verify> functions in the | ||||||||||||||||||||||||||||
| 312 | authenticated encryption modules C<Crypt::AuthEnc::*>. | ||||||||||||||||||||||||||||
| 313 | These return C<undef> when authentication fails, indicating the ciphertext was tampered with | ||||||||||||||||||||||||||||
| 314 | or the wrong key/nonce was used. Some parser/decoder helpers in other modules | ||||||||||||||||||||||||||||
| 315 | also return C<undef> or false for malformed input, so check the concrete | ||||||||||||||||||||||||||||
| 316 | module POD when you need exact failure semantics. | ||||||||||||||||||||||||||||
| 317 | |||||||||||||||||||||||||||||
| 318 | =head2 Module Map | ||||||||||||||||||||||||||||
| 319 | |||||||||||||||||||||||||||||
| 320 | =over | ||||||||||||||||||||||||||||
| 321 | |||||||||||||||||||||||||||||
| 322 | =item * Top-level family modules | ||||||||||||||||||||||||||||
| 323 | |||||||||||||||||||||||||||||
| 324 | L<Crypt::Cipher>, L<Crypt::Mode>, L<Crypt::AuthEnc>, | ||||||||||||||||||||||||||||
| 325 | L<Crypt::Digest>, L<Crypt::Mac>, L<Crypt::Checksum>, L<Crypt::PRNG>, | ||||||||||||||||||||||||||||
| 326 | L<Crypt::PK>, L<Crypt::KeyDerivation>, L<Crypt::Misc>, L<Crypt::ASN1> | ||||||||||||||||||||||||||||
| 327 | |||||||||||||||||||||||||||||
| 328 | =item * Symmetric ciphers | ||||||||||||||||||||||||||||
| 329 | |||||||||||||||||||||||||||||
| 330 | L<Crypt::Cipher::AES>, L<Crypt::Cipher::Anubis>, L<Crypt::Cipher::ARIA>, L<Crypt::Cipher::Blowfish>, L<Crypt::Cipher::Camellia>, L<Crypt::Cipher::CAST5>, L<Crypt::Cipher::DES>, | ||||||||||||||||||||||||||||
| 331 | L<Crypt::Cipher::DES_EDE>, L<Crypt::Cipher::IDEA>, L<Crypt::Cipher::KASUMI>, L<Crypt::Cipher::Khazad>, L<Crypt::Cipher::MULTI2>, L<Crypt::Cipher::Noekeon>, | ||||||||||||||||||||||||||||
| 332 | L<Crypt::Cipher::RC2>, L<Crypt::Cipher::RC5>, L<Crypt::Cipher::RC6>, L<Crypt::Cipher::SAFERP>, L<Crypt::Cipher::SAFER_K128>, L<Crypt::Cipher::SAFER_K64>, | ||||||||||||||||||||||||||||
| 333 | L<Crypt::Cipher::SAFER_SK128>, L<Crypt::Cipher::SAFER_SK64>, L<Crypt::Cipher::SEED>, L<Crypt::Cipher::SM4>, L<Crypt::Cipher::Serpent>, L<Crypt::Cipher::Skipjack>, | ||||||||||||||||||||||||||||
| 334 | L<Crypt::Cipher::Twofish>, L<Crypt::Cipher::XTEA> | ||||||||||||||||||||||||||||
| 335 | |||||||||||||||||||||||||||||
| 336 | =item * Block cipher modes | ||||||||||||||||||||||||||||
| 337 | |||||||||||||||||||||||||||||
| 338 | L<Crypt::Mode::CBC>, L<Crypt::Mode::CFB>, L<Crypt::Mode::CTR>, L<Crypt::Mode::ECB>, L<Crypt::Mode::OFB>, L<Crypt::Mode::XTS> | ||||||||||||||||||||||||||||
| 339 | |||||||||||||||||||||||||||||
| 340 | =item * Stream ciphers | ||||||||||||||||||||||||||||
| 341 | |||||||||||||||||||||||||||||
| 342 | L<Crypt::Stream::RC4>, L<Crypt::Stream::ChaCha>, L<Crypt::Stream::XChaCha>, L<Crypt::Stream::Salsa20>, L<Crypt::Stream::XSalsa20>, | ||||||||||||||||||||||||||||
| 343 | L<Crypt::Stream::Sober128>, L<Crypt::Stream::Sosemanuk>, L<Crypt::Stream::Rabbit> | ||||||||||||||||||||||||||||
| 344 | |||||||||||||||||||||||||||||
| 345 | =item * Authenticated encryption modes | ||||||||||||||||||||||||||||
| 346 | |||||||||||||||||||||||||||||
| 347 | L<Crypt::AuthEnc::CCM>, L<Crypt::AuthEnc::EAX>, L<Crypt::AuthEnc::GCM>, L<Crypt::AuthEnc::GCMSIV>, L<Crypt::AuthEnc::OCB>, L<Crypt::AuthEnc::ChaCha20Poly1305>, L<Crypt::AuthEnc::XChaCha20Poly1305>, L<Crypt::AuthEnc::SIV> | ||||||||||||||||||||||||||||
| 348 | |||||||||||||||||||||||||||||
| 349 | =item * Hash functions | ||||||||||||||||||||||||||||
| 350 | |||||||||||||||||||||||||||||
| 351 | L<Crypt::Digest::BLAKE2b_160>, L<Crypt::Digest::BLAKE2b_256>, L<Crypt::Digest::BLAKE2b_384>, L<Crypt::Digest::BLAKE2b_512>, | ||||||||||||||||||||||||||||
| 352 | L<Crypt::Digest::BLAKE2s_128>, L<Crypt::Digest::BLAKE2s_160>, L<Crypt::Digest::BLAKE2s_224>, L<Crypt::Digest::BLAKE2s_256>, L<Crypt::Digest::BLAKE3>, | ||||||||||||||||||||||||||||
| 353 | L<Crypt::Digest::CHAES>, L<Crypt::Digest::MD2>, L<Crypt::Digest::MD4>, L<Crypt::Digest::MD5>, L<Crypt::Digest::RIPEMD128>, L<Crypt::Digest::RIPEMD160>, | ||||||||||||||||||||||||||||
| 354 | L<Crypt::Digest::RIPEMD256>, L<Crypt::Digest::RIPEMD320>, L<Crypt::Digest::SHA1>, L<Crypt::Digest::SHA224>, L<Crypt::Digest::SHA256>, L<Crypt::Digest::SHA384>, | ||||||||||||||||||||||||||||
| 355 | L<Crypt::Digest::SHA512>, L<Crypt::Digest::SHA512_224>, L<Crypt::Digest::SHA512_256>, L<Crypt::Digest::Tiger192>, L<Crypt::Digest::Whirlpool>, | ||||||||||||||||||||||||||||
| 356 | L<Crypt::Digest::Keccak224>, L<Crypt::Digest::Keccak256>, L<Crypt::Digest::Keccak384>, L<Crypt::Digest::Keccak512>, | ||||||||||||||||||||||||||||
| 357 | L<Crypt::Digest::SHA3_224>, L<Crypt::Digest::SHA3_256>, L<Crypt::Digest::SHA3_384>, L<Crypt::Digest::SHA3_512>, L<Crypt::Digest::SHAKE>, | ||||||||||||||||||||||||||||
| 358 | L<Crypt::Digest::TurboSHAKE>, L<Crypt::Digest::KangarooTwelve>, L<Crypt::Digest::SM3> | ||||||||||||||||||||||||||||
| 359 | |||||||||||||||||||||||||||||
| 360 | =item * Checksums | ||||||||||||||||||||||||||||
| 361 | |||||||||||||||||||||||||||||
| 362 | L<Crypt::Checksum::Adler32>, L<Crypt::Checksum::CRC32> | ||||||||||||||||||||||||||||
| 363 | |||||||||||||||||||||||||||||
| 364 | =item * Message authentication codes | ||||||||||||||||||||||||||||
| 365 | |||||||||||||||||||||||||||||
| 366 | L<Crypt::Mac::BLAKE2b>, L<Crypt::Mac::BLAKE2s>, L<Crypt::Mac::F9>, L<Crypt::Mac::HMAC>, L<Crypt::Mac::KMAC>, | ||||||||||||||||||||||||||||
| 367 | L<Crypt::Mac::OMAC>, L<Crypt::Mac::Pelican>, L<Crypt::Mac::PMAC>, L<Crypt::Mac::XCBC>, L<Crypt::Mac::Poly1305> | ||||||||||||||||||||||||||||
| 368 | |||||||||||||||||||||||||||||
| 369 | =item * Public-key cryptography | ||||||||||||||||||||||||||||
| 370 | |||||||||||||||||||||||||||||
| 371 | L<Crypt::PK::RSA>, L<Crypt::PK::DSA>, L<Crypt::PK::ECC>, L<Crypt::PK::DH>, L<Crypt::PK::Ed25519>, L<Crypt::PK::X25519>, L<Crypt::PK::Ed448>, L<Crypt::PK::X448> | ||||||||||||||||||||||||||||
| 372 | |||||||||||||||||||||||||||||
| 373 | =item * Cryptographically secure random number generators | ||||||||||||||||||||||||||||
| 374 | |||||||||||||||||||||||||||||
| 375 | L<Crypt::PRNG::Fortuna>, L<Crypt::PRNG::Yarrow>, L<Crypt::PRNG::RC4>, L<Crypt::PRNG::Sober128>, L<Crypt::PRNG::ChaCha20> | ||||||||||||||||||||||||||||
| 376 | |||||||||||||||||||||||||||||
| 377 | =item * Key derivation functions | ||||||||||||||||||||||||||||
| 378 | |||||||||||||||||||||||||||||
| 379 | L<Crypt::KeyDerivation> | ||||||||||||||||||||||||||||
| 380 | |||||||||||||||||||||||||||||
| 381 | =item * ASN.1 parser | ||||||||||||||||||||||||||||
| 382 | |||||||||||||||||||||||||||||
| 383 | L<Crypt::ASN1> | ||||||||||||||||||||||||||||
| 384 | |||||||||||||||||||||||||||||
| 385 | Use C<Crypt::ASN1> only when you need custom ASN.1 / DER parsing or encoding. | ||||||||||||||||||||||||||||
| 386 | Most common key and certificate formats are already handled by the PK modules. | ||||||||||||||||||||||||||||
| 387 | |||||||||||||||||||||||||||||
| 388 | =item * Miscellaneous helpers | ||||||||||||||||||||||||||||
| 389 | |||||||||||||||||||||||||||||
| 390 | L<Crypt::Misc> (base64/base32/base58 codecs, PEM helpers, constant-time compare, UUID generation, octet increment helpers, and related utility functions) | ||||||||||||||||||||||||||||
| 391 | |||||||||||||||||||||||||||||
| 392 | =back | ||||||||||||||||||||||||||||
| 393 | |||||||||||||||||||||||||||||
| 394 | =head2 Diagnostic Functions | ||||||||||||||||||||||||||||
| 395 | |||||||||||||||||||||||||||||
| 396 | These low-level functions expose details of the bundled LibTomCrypt build. | ||||||||||||||||||||||||||||
| 397 | They are intended for troubleshooting and bug reports, not for regular use. | ||||||||||||||||||||||||||||
| 398 | |||||||||||||||||||||||||||||
| 399 | =head3 ltc_build_settings | ||||||||||||||||||||||||||||
| 400 | |||||||||||||||||||||||||||||
| 401 | my $str = CryptX::ltc_build_settings(); | ||||||||||||||||||||||||||||
| 402 | |||||||||||||||||||||||||||||
| 403 | Returns a multi-line string describing every compile-time option that was | ||||||||||||||||||||||||||||
| 404 | enabled when the bundled LibTomCrypt library was built (ciphers, hashes, | ||||||||||||||||||||||||||||
| 405 | MACs, PK algorithms, compiler flags, etc.). | ||||||||||||||||||||||||||||
| 406 | |||||||||||||||||||||||||||||
| 407 | =head3 ltc_mp_name | ||||||||||||||||||||||||||||
| 408 | |||||||||||||||||||||||||||||
| 409 | my $name = CryptX::ltc_mp_name(); | ||||||||||||||||||||||||||||
| 410 | # e.g. "LTM" (LibTomMath) | ||||||||||||||||||||||||||||
| 411 | |||||||||||||||||||||||||||||
| 412 | Returns the name of the math provider back-end in use. | ||||||||||||||||||||||||||||
| 413 | |||||||||||||||||||||||||||||
| 414 | =head3 ltc_mp_bits_per_digit | ||||||||||||||||||||||||||||
| 415 | |||||||||||||||||||||||||||||
| 416 | my $bits = CryptX::ltc_mp_bits_per_digit(); | ||||||||||||||||||||||||||||
| 417 | # e.g. 60 | ||||||||||||||||||||||||||||
| 418 | |||||||||||||||||||||||||||||
| 419 | Returns the number of bits per digit used by the math provider. | ||||||||||||||||||||||||||||
| 420 | |||||||||||||||||||||||||||||
| 421 | =head2 Math::BigInt backend | ||||||||||||||||||||||||||||
| 422 | |||||||||||||||||||||||||||||
| 423 | Part of CryptX is L<Math::BigInt::LTM>, a L<Math::BigInt> backend based on | ||||||||||||||||||||||||||||
| 424 | the bundled LibTomMath library. It is separate from the cryptographic APIs | ||||||||||||||||||||||||||||
| 425 | above, but it ships in the same distribution and uses the same big-integer | ||||||||||||||||||||||||||||
| 426 | engine that LibTomCrypt relies on. | ||||||||||||||||||||||||||||
| 427 | |||||||||||||||||||||||||||||
| 428 | =head1 LICENSE | ||||||||||||||||||||||||||||
| 429 | |||||||||||||||||||||||||||||
| 430 | This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. | ||||||||||||||||||||||||||||
| 431 | |||||||||||||||||||||||||||||
| 432 | =head1 COPYRIGHT | ||||||||||||||||||||||||||||
| 433 | |||||||||||||||||||||||||||||
| 434 | Copyright (c) 2013-2026 DCIT, a.s. L<https://www.dcit.cz> / Karel Miko | ||||||||||||||||||||||||||||
| 435 | |||||||||||||||||||||||||||||
| 436 | =cut | ||||||||||||||||||||||||||||