/ 
Data-Tools-Crypto-1.53
/ Data::Tools::Crypto

NAME

Data::Tools::Crypto - authenticated symmetric and hybrid RSA encryption and signatures, one common API

SYNOPSIS

# Data::Tools::Crypto is the base class, it is never used on its own,
# use one of the implementations which inherit it:

use Data::Tools::Crypto::Symmetric;
use Data::Tools::Crypto::RSA;

my $crypto = Data::Tools::Crypto::Symmetric->new( $key );

# --------------------------------------------------------------------------

# raw binary data in, raw binary data out

my $ctext = $crypto->encrypt( $ptext );
my $ptext = $crypto->decrypt( $ctext );

# --------------------------------------------------------------------------

# the same, in text-safe encodings

my $hex   = $crypto->encrypt_hex( $ptext );
my $ptext = $crypto->decrypt_hex( $hex   );

my $b64   = $crypto->encrypt_base64( $ptext );
my $ptext = $crypto->decrypt_base64( $b64   );

my $b64u  = $crypto->encrypt_base64url( $ptext );
my $ptext = $crypto->decrypt_base64url( $b64u  );

# --------------------------------------------------------------------------

# any perl data structure, JSON-serialised and encrypted in one step

my $data  = { name => 'test', list => [ 1, 2, 3 ] };

my $sealed = $crypto->freeze( $data   );
my $data   = $crypto->thaw(   $sealed );

my $sealed = $crypto->freeze_hex(       $data   );
my $sealed = $crypto->freeze_base64(    $data   );
my $sealed = $crypto->freeze_base64url( $data   );

# --------------------------------------------------------------------------

DESCRIPTION

Data::Tools::Crypto provides authenticated encryption, hybrid public key encryption and digital signatures, with a single common API:

* Data::Tools::Crypto::Symmetric -- shared secret key, ChaCha20-Poly1305
* Data::Tools::Crypto::RSA       -- public/private key pair, hybrid, signatures

This module is the base class of both. It implements no encryption of its own, it defines the API which every implementation offers and provides the encoding and serialisation wrappers on top of the encrypt() and decrypt() methods that the inheriting module must provide.

Errors behave exactly as in the inheriting module, since every method here goes through its encrypt() or decrypt(): caller errors raise an exception, and data which does not decrypt makes decrypt_*() and thaw*() return undef.

The base class is not usable by itself and has nothing to export, always use one of the implementations listed above.

freeze/thaw use JSON as a safer option than Storable, so only plain data can be carried: hashes, arrays, scalars and numbers. Blessed objects, code references and circular structures cannot be serialised.

METHODS

encrypt( $plaintext ), decrypt( $cryptotext )

Implemented by the inheriting module, not by the base class. All the methods below are built on top of these two.

encrypt_hex( $plaintext ), decrypt_hex( $cryptotext )

As encrypt()/decrypt() but the cryptotext is HEX encoded, so it is plain text and safe to store or pass anywhere a binary string would not survive.

encrypt_base64( $plaintext ), decrypt_base64( $cryptotext )

As encrypt()/decrypt() but the cryptotext is BASE64 encoded, on a single line with no newlines added.

encrypt_base64url( $plaintext ), decrypt_base64url( $cryptotext )

As encrypt_base64() but using the URL and filename safe BASE64 alphabet, so the result can be used in a URL or a file name without further escaping.

freeze( $data_ref ), thaw( $cryptotext )

freeze() serialises any plain perl data structure to JSON and encrypts it. thaw() reverses this and returns the data structure back, or undef if the cryptotext cannot be decrypted, exactly as decrypt() does.

freeze_hex(), freeze_base64(), freeze_base64url() and their thaw pairs

As freeze()/thaw() but with the cryptotext encoded as described above:

my $sealed = $crypto->freeze_hex( $data_ref );
my $data   = $crypto->thaw_hex(   $sealed   );

REQUIRED MODULES

Data::Tools::Crypto uses:

* Data::Tools
* JSON
* MIME::Base64

GITHUB REPOSITORY

https://github.com/cade-vs/perl-data-tools-crypto

git clone https://github.com/cade-vs/perl-data-tools-crypto.git

AUTHOR

Vladi Belperchinov-Shabanski "Cade"
      <cade@noxrun.com> <cade@bis.bg> <cade@cpan.org>
http://cade.noxrun.com/