NOME

CryptX - Kit de ferramentas criptográficas

SINOPSE

CryptX é o ponto de entrada da distribuição. No código normal, carregue um dos módulos concretos listados abaixo.

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

## criptografia clássica AES-CBC com preenchimento
use Crypt::Mode::CBC;
my $cbc = Crypt::Mode::CBC->new('AES');
my $iv = random_bytes(16); # IV de 16 bytes (tamanho do bloco AES)
my $cbc_ciphertext = $cbc->encrypt('hello world', $key, $iv);

## criptografia autenticada (AEAD) com AES
use Crypt::AuthEnc::GCM qw(gcm_encrypt_authenticate);
my $key = random_bytes(32);   # chave AES-256 de 32 bytes
my $nonce = random_bytes(12); # nonce único de 12 bytes
my ($ciphertext, $tag) = gcm_encrypt_authenticate('AES', $key, $nonce, 'header', 'hello world');

## autenticação de mensagens
use Crypt::Mac::HMAC qw(hmac_hex);
my $mac = hmac_hex('SHA256', $key, 'hello world');

## dados aleatórios seguros + auxiliares UUID
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();

## derivação de chave clássica baseada em senha
use Crypt::KeyDerivation qw(pbkdf2);
my $dk = pbkdf2('password', $salt, 100_000, 'SHA256', 32);

## cifra de fluxo simples (autentique separadamente)
use Crypt::Stream::ChaCha;
my $stream = Crypt::Stream::ChaCha->new($key, $nonce);
my $stream_ciphertext = $stream->crypt('hello world');

## assinaturas modernas
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');

## acordo de chaves
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);

DESCRIÇÃO

Módulos criptográficos Perl construídos sobre a biblioteca LibTomCrypt empacotada. A distribuição também inclui Math::BigInt::LTM, um backend para Math::BigInt construído sobre a biblioteca LibTomMath empacotada usada internamente pelo LibTomCrypt.

Este módulo serve principalmente como página de topo da distribuição/documentação. Para trabalho real, use um dos módulos concretos listados abaixo.

Guia de Seleção de Algoritmos

Criptografia Autenticada (AEAD)

Para novos projetos, prefira criptografia autenticada (AEAD) a modos de cifra simples:

• ChaCha20-Poly1305 (Crypt::AuthEnc::ChaCha20Poly1305) - Rápido, tempo constante, amplamente implantado (TLS 1.3, WireGuard, SSH). Use como escolha padrão de AEAD.
• XChaCha20-Poly1305 (Crypt::AuthEnc::XChaCha20Poly1305) - Variante com nonce estendido de 24 bytes. Prefira em relação ao ChaCha20-Poly1305 quando os nonces forem gerados aleatoriamente.
• AES-GCM (Crypt::AuthEnc::GCM) - O modo AEAD padrão para AES. Acelerado por hardware em CPUs modernas. Requer nonces únicos; a reutilização de nonce quebra totalmente a segurança.
• AES-SIV (Crypt::AuthEnc::SIV) - AEAD determinístico, resistente ao mau uso de nonce. Ligeiramente mais lento, mas mais seguro quando a unicidade do nonce não pode ser garantida.
• AES-GCM-SIV (Crypt::AuthEnc::GCMSIV) - AEAD resistente ao mau uso de nonce (RFC 8452). Mais rápido que AES-SIV; escolha-o quando precisar de desempenho semelhante ao GCM com segurança contra reutilização de nonce.
• AES-OCB (Crypt::AuthEnc::OCB) - AEAD de passagem única muito rápido. Verifique o status de patente para sua jurisdição.
• AES-EAX (Crypt::AuthEnc::EAX) - AEAD de duas passagens baseado em CTR+OMAC. Sem patentes, sem restrições de tamanho de nonce.
• AES-CCM (Crypt::AuthEnc::CCM) - Usado em WiFi (WPA2) e Bluetooth. Requer conhecer o comprimento do texto simples com antecedência.

Aleatoriedade Criptograficamente Segura e UUIDs

• Bytes / strings aleatórios (Crypt::PRNG) - Use para salts, chaves, nonces, tokens e quaisquer outros valores aleatórios secretos. Os helpers funcionais random_bytes, random_bytes_hex, random_bytes_b64, random_bytes_b64u, random_string e random_string_from cobrem a maioria dos casos de uso. A API OO e os wrappers específicos de algoritmo (Crypt::PRNG::ChaCha20, Crypt::PRNG::Fortuna, etc.) são principalmente para fluxos determinísticos ou interoperabilidade com um PRNG específico.
• UUIDs ("random_v4uuid" em Crypt::Misc, "random_v7uuid" em Crypt::Misc) - Use random_v4uuid para identificadores aleatórios opacos. Use random_v7uuid quando quiser identificadores aproximadamente ordenados por tempo que se classificam por tempo de criação com granularidade de milissegundos. UUIDs são identificadores, não substitutos para bytes aleatórios secretos.

Cifras de Fluxo

Cifras de fluxo criptografam dados byte a byte sem preenchimento de bloco. Para a maioria das aplicações, prefira um modo AEAD (veja acima) que combina criptografia com autenticação. Use cifras de fluxo simples apenas quando você lidar com autenticação separadamente.

• ChaCha (Crypt::Stream::ChaCha) - A escolha padrão de cifra de fluxo. Mesmo núcleo do ChaCha20-Poly1305 sem o MAC embutido.
• XChaCha (Crypt::Stream::XChaCha) - Variante com nonce estendido de 24 bytes do ChaCha. Prefira quando os nonces forem gerados aleatoriamente.
• Salsa20 / XSalsa20 (Crypt::Stream::Salsa20, Crypt::Stream::XSalsa20) - Predecessor do ChaCha. Prefira ChaCha para novos projetos; Salsa20 apenas para interoperabilidade (ex.: NaCl/libsodium).
• RC4 (Crypt::Stream::RC4) - Quebrado; não use para novos projetos. Fornecido apenas para interoperabilidade legada.
• Rabbit, Sober128, Sosemanuk (Crypt::Stream::Rabbit, Crypt::Stream::Sober128, Crypt::Stream::Sosemanuk) - Cifras de nicho do portfólio eSTREAM. Use ChaCha a menos que um protocolo específico exija um deles.

Modos de Cifra de Bloco (sem autenticação)

Use estes apenas quando a autenticação for tratada separadamente ou não for necessária:

• CTR (Crypt::Mode::CTR) - Transforma uma cifra de bloco em uma cifra de fluxo. Paralelizável.
• CBC (Crypt::Mode::CBC) - Modo clássico, precisa de preenchimento. Prefira CTR ou um modo AEAD.
• ECB (Crypt::Mode::ECB) - Inseguro para a maioria dos usos. Cada bloco criptografado independentemente.

Os módulos individuais Crypt::Cipher::AES, Crypt::Cipher::Twofish, etc. implementam criptografia bruta de bloco único e raramente são usados diretamente. Na maioria dos casos, você deve usá-los através de um modo AEAD (Crypt::AuthEnc::GCM, Crypt::AuthEnc::CCM) ou um modo de cifra de bloco (Crypt::Mode::CBC, Crypt::Mode::CTR). Ao escolher uma cifra, AES é o padrão; é acelerado por hardware na maioria das CPUs modernas.

Funções Hash

• SHA-256 / SHA-384 / SHA-512 (Crypt::Digest::SHA256, etc.) - A escolha padrão para hashing geral. Amplamente suportado e bem analisado.
• SHA3-256 / SHA3-512 (Crypt::Digest::SHA3_256, etc.) - Alternativa ao SHA-2 com uma construção completamente diferente (esponja Keccak).
• BLAKE2b / BLAKE2s (Crypt::Digest::BLAKE2b_256, etc.) - Muito rápido, especialmente em software. BLAKE2b para plataformas de 64 bits, BLAKE2s para 32 bits.
• SHAKE / TurboSHAKE / KangarooTwelve - Funções de saída extensível (XOFs). Use quando precisar de saída de comprimento variável.

Checksums (Somas de Verificação)

Use Crypt::Checksum::CRC32 e Crypt::Checksum::Adler32 apenas para verificações de integridade não adversariais, como detecção de corrupção acidental. Eles não são mecanismos de integridade ou autenticação criptográfica. Para uso criptográfico, prefira Crypt::Digest, Crypt::Mac ou um modo AEAD de Crypt::AuthEnc.

Códigos de Autenticação de Mensagens

• HMAC (Crypt::Mac::HMAC) - A construção MAC padrão. Funciona com qualquer hash. Use HMAC-SHA256 como padrão.
• Poly1305 (Crypt::Mac::Poly1305) - MAC de uso único, muito rápido. Usado como parte do ChaCha20-Poly1305. Requer uma chave única por mensagem.
• BLAKE2b-MAC (Crypt::Mac::BLAKE2b) - BLAKE2 com chave. Mais rápido que HMAC-SHA256 em software.
• CMAC/OMAC (Crypt::Mac::OMAC) - MAC baseado em cifra de bloco. Use quando já tiver AES mas não uma função hash.

Criptografia de Chave Pública

• Ed25519 (Crypt::PK::Ed25519) - Assinaturas digitais modernas. Rápido, tempo constante, chaves/assinaturas pequenas. A escolha padrão para novos esquemas de assinatura.
• Ed448 (Crypt::PK::Ed448) - Margem de segurança maior que Ed25519 (~224 bits vs ~128 bits).
• X25519 (Crypt::PK::X25519) - Acordo de chaves Diffie-Hellman de curva elíptica. A escolha padrão para troca de chaves.
• X448 (Crypt::PK::X448) - Margem de segurança maior que X25519.
• ECDSA (Crypt::PK::ECC) - Amplamente usado (TLS, Bitcoin). Prefira Ed25519 para novos projetos, a menos que ECDSA seja exigido para interoperabilidade.
• RSA (Crypt::PK::RSA) - Legado, mas muito usado. Use chaves de no mínimo 2048 bits, de preferência 4096 bits. Prefira OAEP para criptografia e PSS para assinaturas.
• DSA (Crypt::PK::DSA) - Legado. Prefira Ed25519 ou ECDSA.
• DH (Crypt::PK::DH) - Diffie-Hellman clássico. Prefira X25519 para novos projetos.

Derivação de Chave / Hash de Senha

• HKDF ("hkdf" em Crypt::KeyDerivation) - KDF de extrair-depois-expandir. Use para derivar chaves de segredos compartilhados (ex.: após ECDH).
• Argon2 ("argon2_pbkdf" em Crypt::KeyDerivation) - Hash de senha com uso intensivo de memória. A escolha recomendada para armazenamento de senhas.
• Bcrypt ("bcrypt_pbkdf" em Crypt::KeyDerivation) - Use principalmente para compatibilidade com formatos e protocolos que exigem especificamente derivação de chave baseada em bcrypt (por exemplo, alguns fluxos de trabalho do OpenSSH). Prefira Argon2 para novos projetos de armazenamento de senhas.
• Scrypt ("scrypt_pbkdf" em Crypt::KeyDerivation) - KDF com uso intensivo de memória. Use Argon2 se disponível.
• PBKDF2 ("pbkdf2" em Crypt::KeyDerivation) - Amplamente suportado, mas apenas com dificuldade de CPU. Use Argon2 ou Scrypt quando possível.
• PBKDF1 ("pbkdf1" em Crypt::KeyDerivation, "pbkdf1_openssl" em Crypt::KeyDerivation) - Derivação legada apenas. Mantenha para interoperabilidade com formatos mais antigos; não use para novos projetos.

Tratamento de Erros

A maioria dos módulos CryptX relata erros chamando croak (de Carp). Parâmetros inválidos, algoritmos não suportados, tamanhos de chave errados, entrada malformada e falhas internas da biblioteca geralmente chamam croak com uma mensagem descritiva. Capture exceções com eval ou Try::Tiny.

Alguns helpers de validação usam um valor de retorno em vez de croak. Os exemplos mais importantes são as funções *_decrypt_verify nos módulos de criptografia autenticada Crypt::AuthEnc::*. Estas retornam undef quando a autenticação falha, indicando que o texto cifrado foi adulterado ou a chave/nonce errado foi usado. Alguns helpers de análise/decodificação em outros módulos também retornam undef ou falso para entrada malformada, então verifique o POD do módulo concreto quando precisar de semântica exata de falha.

Mapa de Módulos

• Módulos de família de topo

  Crypt::Cipher, Crypt::Mode, Crypt::AuthEnc, Crypt::Digest, Crypt::Mac, Crypt::Checksum, Crypt::PRNG, Crypt::PK, Crypt::KeyDerivation, Crypt::Misc, Crypt::ASN1

• Cifras simétricas

  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, , , , , , , , , , , , ,

Funções de Diagnóstico

Estas funções de baixo nível expõem detalhes da construção do LibTomCrypt incluído. Destinam-se a resolução de problemas e relatórios de bugs, não para uso regular.

ltc_build_settings

my $str = CryptX::ltc_build_settings();

Retorna uma string de múltiplas linhas descrevendo cada opção de tempo de compilação que foi ativada quando a biblioteca LibTomCrypt incluída foi construída (cifras, hashes, MACs, algoritmos PK, flags do compilador, etc.).

ltc_mp_name

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

Retorna o nome do provedor matemático back-end em uso.

ltc_mp_bits_per_digit

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

Retorna o número de bits por dígito usado pelo provedor matemático.

Backend Math::BigInt

Parte do CryptX é o Math::BigInt::LTM, um backend Math::BigInt baseado na biblioteca LibTomMath incluída. Ele é separado das APIs criptográficas acima, mas é distribuído no mesmo pacote e usa o mesmo motor de inteiros grandes do qual LibTomCrypt depende.

LICENÇA

Este programa é software livre; você pode redistribuí-lo e/ou modificá-lo sob os mesmos termos que o próprio Perl.

DIREITOS AUTORAIS

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