NAME

Crypto::Util - A lightweight Crypt/Digest convenience API

SYNOPSIS

        use Crypto::Util; # also has a Sub::Exporter to return functions wrapping a default instance

        my $util = Crypto::Util->new;

        $util->default_key("my secret");

        # MAC or cipher+digest based tamper resistent encapsulation

        my $tamper_resistent_string = $util->tamper_protected( $data ); # can also take refs

        my $trusted = $util->thaw_tamper_protected( $untrusted_string, key => "another secret" );

        # without specifying which encoding returns base32 or hex if base32 is unavailable
        my $encoded = $util->encode_string( $bytes );

        my $hash = $util->digest( $bytes, digest => "md5" );

        die "baaaad" unless $util->verify_hash(
                hash => $hash,
                data => $bytes,
                digest => "md5",
        );

ACHTUNG!

This is a sloppy release. By 0.01 the docs should be in place, as well as some more features I want in. As the saying goes, release prematurely, cry often.

DESCRIPTION

This module provides an easy, intuitive and forgiving API for weilding crypto-fu.

Features which are currently missing but are scheduled for 0.01:

• xMAC support

• Crypt::SaltedHash support

• Bruce Schneier Fact Database http://geekz.co.uk/lovesraymond/archive/bruce-schneier-facts

• Entropy fetching (get N weak/strong bytes, etc) from e.g. OpenSSL bindings, /dev/*random, and EGD.

• Pipelined encrypting/digesting... Currently all the methods are named foo_string. In the future, a foo variant that auto DWIMs will be added, and a foo_stream, foo_handle, foo_callbacks api will be layered over a simple push API (like Crypt::CBC).

PRIORITIES

Ease of use

Usability patches are very welcome - this is supposed to be an easy api for random people to be able to easily (but responsibly) use the more low level Crypt:: and Digest:: modules on the CPAN.

Pluggability

Dependency hell is avoided using a fallback mechanism that tries to choose an algorithm based on an overridable list.

For "simple" use install Crypt::Util and your favourite digest, cipher and cipher mode (CBC, CFB, etc).

To ensure predictable behavior the fallback behavior can be disabled as necessary.

METHODS

tamper_protected [ $data ] %params

thaw_tamper_protected [ $string ] %params

tamper_unprotected [ $string ] %params

params: data => $anything, encrypt => bool || alg (defaults to true, false means just hmac), key (encrypt_string), digest => bool || alg, encode => bool || alg (defaults to true/"uri", see encode string), fatal => bool (defaults to true, turning it off will return undef on failure instead of dying)

with odd args the first is treated as data

implicitly storables data if it's a ref

encrypt_string [ $string ] %params

decrypt_string [ $string ] %params

encode => bool || alg (defaults to false), encrypt => bool || alg, key (defaults to server_key)

with odd args the firstr is treated as the string

cipher_object %params

params: cipher, key

Return an object using Crypt::CBC

digest_string [ $string ] %params

digest => alg

with odd args the firstr is treated as the string

verify_digest

hash => string (the hash to verify), string => string (the digested string), all params of digest_string, fatal => bool (defaults to false)

just calls digest_string and then eq

digest_object %params

params: digest

Returns an object using Digest

encode_string [ $string ] %params

decode_string [ $string ] %params

encoding => symbolic type (uri, printable) or concrete type (none, hex, base64, base32)

mac_digest_string [ $string ] %params

verify_mac %params

XXX emac, hmac, etc wrapper?

mac => string (the mac to verify), string => string (the digested string), type => "digest" || "cipher" # hmac or cmac, fatal => bool (defaults to false, whbich just returns undef on failure)

hmac_digest_string %params

verify_hmac %params

mac => string (the mac to verify), string => string (the digested string), fatal => bool (defaults to false), all params of hmac_digest_string

cmac_digest_string %params

verify_cmac

cmac, emac

with odd args the firstr is treated as the string

weak_random_string %params

A fairly entropic random string, suitable for digesting

digest => bool || alg (defaults to true), encode bool || alg

strong_random_string %params

digest => bool || alg (defaults to false), encode bool || alg, bytes => $n (defaults to 32)

might not be supported (tries /dev/random and/or the OpenSSL bindings)

encode_string_alphanumerical $string

decode_string_alphanumerical $string

encode_string_uri $string

decode_string_uri $string

encoding into a URI safe string

encode_string_printable $string

decode_string_printable $string

encode_string_hex $string

decode_string_hex $string

encode_string_uri_escape $string

decode_string_uri_escape $string

encode_string_base64 $string

decode_string_base64 $string

encode_string_base32 $string

decode_string_base32 $string

# "default" is there to be overridden by configs, if it returns nothing fallback will be called # "fallback" is for when nothing is configured -- the class's default

disable

When true only the first item from the fallback list will be tried, and if it can't be loaded there will be loud deaths.

Enable this to ensure portability

default_key

default_cipher

fallback_cipher

find the first from fallback_cipher_list

fallback_cipher_list

qw/Rijndael Twofish Blowfish IDEA RC6 RC5/;

default_digest

fallback_digest

fallback_digest_list

qw/SHA1 RIPEMD-160 Whirlpool MD5/

default_encoding

fallback_encoding

fallback_encoding_list

"hex"

default_alphanumerical_encoding

fallback_alphanumerical_encoding

fallback_alphanumerical_encoding_list

"base32", "hex"

default_uri_encoding

fallback_uri_encoding

fallback_uri_encoding_list

"uri_base64" # XXX make this uri_escape?

default_printable_encoding

fallback_printable_encoding

"base64"