| File::KDBX::Cipher(3pm) | User Contributed Perl Documentation | File::KDBX::Cipher(3pm) |
File::KDBX::Cipher - A block cipher mode or cipher stream
version 0.906
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;
A cipher is used to encrypt and decrypt KDBX files. The File::KDBX distribution comes with several pre-registered ciphers ready to go:
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 { ... }
$uuid = $cipher->uuid;
Get the UUID if the cipher was constructed with one.
$stream_id = $cipher->stream_id;
Get the stream ID if the cipher was constructed with one.
$key = $cipher->key;
Get the raw encryption key.
$iv = $cipher->iv;
Get the initialization vector.
$size = $cipher->iv_size;
Get the expected size of the initialization vector, in bytes.
$size = $cipher->key_size;
Get the size the mode or stream expects the key to be, in bytes.
$size = $cipher->block_size;
Get the block size, in bytes.
Get the symmetric cipher algorithm.
$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.
$self->init;
Called by "new" to set attributes. You normally shouldn't call this. Returns itself to allow method chaining.
$ciphertext = $cipher->encrypt($plaintext, ...);
Encrypt some data.
$plaintext = $cipher->decrypt($ciphertext, ...);
Decrypt some data.
$ciphertext .= $cipher->finish; # if encrypting
$plaintext .= $cipher->finish; # if decrypting
Finish the stream.
$ciphertext = $cipher->encrypt_finish($plaintext, ...);
Encrypt and finish a stream in one call.
$plaintext = $cipher->decrypt_finish($ciphertext, ...);
Decrypt and finish a stream in one call.
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.
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").
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.
Charles McGarvey <ccm@cpan.org>
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.
| 2022-11-20 | perl v5.36.0 |