/ 
CryptX-0.088_005
⭐ Starred 36 / README.md

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 library. The distribution also includes Math::BigInt::LTM, a Math::BigInt backend built on the bundled 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:

Cryptographically Secure Randomness and UUIDs

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.

Block Cipher Modes (without authentication)

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

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

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

Public-Key Cryptography

Key Derivation / Password hashing

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

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