/ 
Data-Tools-Crypto-1.52
/ Data::Tools::Crypto::Base

NAME

Data::Tools::Crypto::Base - common encryption API shared by the Data::Tools::Crypto modules

SYNOPSIS

# Base is never used on its own, it is inherited by the crypto modules:

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::Base implements no encryption of its own. It defines the API which every Data::Tools::Crypto module offers, and implements 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.

There is no Data::Tools::Crypto module, the base class is not usable by itself and has nothing to export. Use one of the implementations instead:

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

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 Base. 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::Base 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/