view release on metacpan or  search on metacpan

lib/Crypt/NamedKeys.pod  view on Meta::CPAN

=encoding utf8

=for comment POD_DERIVED_INDEX_GENERATED
The following documentation is automatically generated.  Please do not edit
this file, but rather the original, inline with Crypt::NamedKeys
at lib/Crypt/NamedKeys.pm
(on the system that originally ran this).
If you do edit this file, and don't want your changes to be removed, make
sure you change the first line.

=cut

=head1 NAME

Crypt::NamedKeys - A Crypt::CBC wrapper with key rotation support

=head1 SYNOPSYS

    use Crypt::NamedKeys;
    my $crypt = Crypt::NamedKeys->new(keyname => 'href');
    my $encrypted = $crypt->encrypt_data(data => $href);
    my $restored_href = $crypt->decrypt_data(
        data => $encrypted->{data},
        mac  => $encrypted->{mac},
    );

=head1 DESCRIPTION

This module provides functions to serialize data for transfer via non-protected
channels with encryption and data integrity protection.  The module tracks key
number used to encrypt information so that keys can be rotated without making
data unreadable.

=head1 CONFIGURATION AND KEY ROTATION

The keys are stored in the keyfile, configurable as below.  Keys are numbered
starting at 1.  Numbers must never be reused.  Typically key rotation will be
done in several steps, each with its own rollout.  These steps MUST be done as
separate releases because otherwise keys may not be available to decrypt data,
and so things may not work.

=head2 keyfile location

The keyfile can be set using the keyfile($path) function.  There is no default.

=head2 keyfile format

The format of the keyfile is YAML, following a basic structure of

 keyname:
    [keyhashdef]

so for example:

 cryptedfeed:
    default_keynum: 9
    none: queith7eeTh0teejaichoodobooX9ceechee9Sai9gauChiengaeraew3aDiehei
    1: aePh8ahBaNg1bee6ohj3er5cuzeepoophai1oogohpoixothah4AuYiongu4ahta
    2: oht1eep8uxoo1eeshaSaemee9aem5chahqueu0Aedaa7eeXae9aeghe5umoNah6a
    3: chigh4veifoofe0Vohphee4ohkaef9giz2iaje2ahF4ohboSh6ifaiNgohwohchi
    4: Ahphahmisaingo5Ietheangeegi5ia1uuF9taerooShaitoh1Eophig3ohziejet
    5: oe5wi2equee6FeiZohjah2peas6Ahquohniefeimai0beip2waxeizoo1OhthohN
    6: eigaezee3CeuC8phae4giph6Miqu6piy3Eideipahticesheij7se9eecai9fiez
    7: DuuGhohViGh0Sheihahr6ce4Phuin7ahpaiSa5jaiphie3eiz8oa3dohrohghuow
    8: ahfoniemah4boemeN8seJ7hohhualeetei7aegohhai5ohwahlohnah2Ee2Ewal1
    9: Ceixei4shelohxee1ohdoochuliebael1kae8eit0Geeth1so9fohZi0cohs8go4
    10: boreiDe0shueNgie7shai7ooc1yaeveiKeihuox0xahp1hai8phe7aephiel2oob

In general we assume key spefications to use numeric keys within the named
key hash.  This makes key rotation a lot easier and prevents reusing key
numbers.

Key names may not contain = or -.

All keys listed can be used for decryption (with the special 'none' key used if