NAME

       File::KDBX::Cipher - A block cipher mode or cipher stream

VERSION

       version 0.906

SYNOPSIS

           use File::KDBX::Cipher;

           my $cipher = File::KDBX::Cipher->new(uuid => $uuid, key => $key, iv => $iv);

           my $ciphertext = $cipher->encrypt('plaintext');
           $ciphertext .= $cipher->encrypt('more plaintext');
           $ciphertext .= $cipher->finish;

           my $plaintext = $cipher->decrypt('ciphertext');
           $plaintext .= $cipher->decrypt('more ciphertext');
           $plaintext .= $cipher->finish;

DESCRIPTION

       A cipher is used to encrypt and decrypt KDBX files. The File::KDBX distribution comes with
       several pre-registered ciphers ready to go:

       •   "61AB05A1-9464-41C3-8D74-3A563DF8DD35" - AES128 (legacy)

       •   "31C1F2E6-BF71-4350-BE58-05216AFC5AFF" - AES256

       •   "D6038A2B-8B6F-4CB5-A524-339A31DBB59A" - ChaCha20

       •   "716E1C8A-EE17-4BDC-93AE-A977B882833A" - Salsa20

       •   "098563FF-DDF7-4F98-8619-8079F6DB897A" - Serpent

       •   "AD68F29F-576F-4BB9-A36A-D47AF965346C" - Twofish

       NOTE: If you want your KDBX file to be readable by other KeePass implementations, you must
       use a UUID and algorithm that they support. From the list above, AES256 and ChaCha20 are
       well-supported. You should avoid AES128 for new databases.

       You can also "register" your own cipher. Here is a skeleton:

           package File::KDBX::Cipher::MyCipher;

           use parent 'File::KDBX::Cipher';

           File::KDBX::Cipher->register(
               # $uuid, $package, %args
               "\x12\x34\x56\x78\x9a\xbc\xde\xfg\x12\x34\x56\x78\x9a\xbc\xde\xfg" => __PACKAGE__,
           );

           sub init { ... } # optional

           sub encrypt { ... }
           sub decrypt { ... }
           sub finish  { ... }

           sub key_size   { ... }
           sub iv_size    { ... }
           sub block_size { ... }

ATTRIBUTES

   uuid
           $uuid = $cipher->uuid;

       Get the UUID if the cipher was constructed with one.

   stream_id
           $stream_id = $cipher->stream_id;

       Get the stream ID if the cipher was constructed with one.

   key
           $key = $cipher->key;

       Get the raw encryption key.

   iv
           $iv = $cipher->iv;

       Get the initialization vector.

   iv_size
           $size = $cipher->iv_size;

       Get the expected size of the initialization vector, in bytes.

   key_size
           $size = $cipher->key_size;

       Get the size the mode or stream expects the key to be, in bytes.

   block_size
           $size = $cipher->block_size;

       Get the block size, in bytes.

   algorithm
       Get the symmetric cipher algorithm.

METHODS

   new
   new_from_uuid
   new_from_stream_id
           $cipher = File::KDBX::Cipher->new(uuid => $uuid, key => $key, iv => $iv);
           # OR
           $cipher = File::KDBX::Cipher->new_from_uuid($uuid, key => $key, iv => $iv);

           $cipher = File::KDBX::Cipher->new(stream_id => $id, key => $key);
           # OR
           $cipher = File::KDBX::Cipher->new_from_stream_id($id, key => $key);

       Construct a new File::KDBX::Cipher.

       This is a factory method which returns a subclass.

   init
           $self->init;

       Called by "new" to set attributes. You normally shouldn't call this. Returns itself to
       allow method chaining.

   encrypt
           $ciphertext = $cipher->encrypt($plaintext, ...);

       Encrypt some data.

   decrypt
           $plaintext = $cipher->decrypt($ciphertext, ...);

       Decrypt some data.

   finish
           $ciphertext .= $cipher->finish; # if encrypting
           $plaintext  .= $cipher->finish; # if decrypting

       Finish the stream.

   encrypt_finish
           $ciphertext = $cipher->encrypt_finish($plaintext, ...);

       Encrypt and finish a stream in one call.

   decrypt_finish
           $plaintext = $cipher->decrypt_finish($ciphertext, ...);

       Decrypt and finish a stream in one call.

   register
           File::KDBX::Cipher->register($uuid => $package, %args);

       Register a cipher. Registered ciphers can be used to encrypt and decrypt KDBX databases. A
       cipher's UUID must be unique and musn't change. A cipher UUID is written into each KDBX
       file and the associated cipher must be registered with the same UUID in order to decrypt
       the KDBX file.

       $package should be a Perl package relative to "File::KDBX::Cipher::" or prefixed with a
       "+" if it is a fully-qualified package. %args are passed as-is to the cipher's "init"
       method.

   unregister
           File::KDBX::Cipher->unregister($uuid);

       Unregister a cipher. Unregistered ciphers can no longer be used to encrypt and decrypt
       KDBX databases, until reregistered (see "register").

BUGS

       Please report any bugs or feature requests on the bugtracker website
       <https://github.com/chazmcgarvey/File-KDBX/issues>

       When submitting a bug or request, please include a test-file or a patch to an existing
       test-file that illustrates the bug or desired feature.

AUTHOR

       Charles McGarvey <ccm@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2022 by Charles McGarvey.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.