1File::KDBX::Cipher(3) User Contributed Perl DocumentationFile::KDBX::Cipher(3)
2
3
4

NAME

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

VERSION

9       version 0.906
10

SYNOPSIS

12           use File::KDBX::Cipher;
13
14           my $cipher = File::KDBX::Cipher->new(uuid => $uuid, key => $key, iv => $iv);
15
16           my $ciphertext = $cipher->encrypt('plaintext');
17           $ciphertext .= $cipher->encrypt('more plaintext');
18           $ciphertext .= $cipher->finish;
19
20           my $plaintext = $cipher->decrypt('ciphertext');
21           $plaintext .= $cipher->decrypt('more ciphertext');
22           $plaintext .= $cipher->finish;
23

DESCRIPTION

25       A cipher is used to encrypt and decrypt KDBX files. The File::KDBX
26       distribution comes with several pre-registered ciphers ready to go:
27
28       •   "61AB05A1-9464-41C3-8D74-3A563DF8DD35" - AES128 (legacy)
29
30       •   "31C1F2E6-BF71-4350-BE58-05216AFC5AFF" - AES256
31
32       •   "D6038A2B-8B6F-4CB5-A524-339A31DBB59A" - ChaCha20
33
34       •   "716E1C8A-EE17-4BDC-93AE-A977B882833A" - Salsa20
35
36       •   "098563FF-DDF7-4F98-8619-8079F6DB897A" - Serpent
37
38       •   "AD68F29F-576F-4BB9-A36A-D47AF965346C" - Twofish
39
40       NOTE: If you want your KDBX file to be readable by other KeePass
41       implementations, you must use a UUID and algorithm that they support.
42       From the list above, AES256 and ChaCha20 are well-supported. You should
43       avoid AES128 for new databases.
44
45       You can also "register" your own cipher. Here is a skeleton:
46
47           package File::KDBX::Cipher::MyCipher;
48
49           use parent 'File::KDBX::Cipher';
50
51           File::KDBX::Cipher->register(
52               # $uuid, $package, %args
53               "\x12\x34\x56\x78\x9a\xbc\xde\xfg\x12\x34\x56\x78\x9a\xbc\xde\xfg" => __PACKAGE__,
54           );
55
56           sub init { ... } # optional
57
58           sub encrypt { ... }
59           sub decrypt { ... }
60           sub finish  { ... }
61
62           sub key_size   { ... }
63           sub iv_size    { ... }
64           sub block_size { ... }
65

ATTRIBUTES

67   uuid
68           $uuid = $cipher->uuid;
69
70       Get the UUID if the cipher was constructed with one.
71
72   stream_id
73           $stream_id = $cipher->stream_id;
74
75       Get the stream ID if the cipher was constructed with one.
76
77   key
78           $key = $cipher->key;
79
80       Get the raw encryption key.
81
82   iv
83           $iv = $cipher->iv;
84
85       Get the initialization vector.
86
87   iv_size
88           $size = $cipher->iv_size;
89
90       Get the expected size of the initialization vector, in bytes.
91
92   key_size
93           $size = $cipher->key_size;
94
95       Get the size the mode or stream expects the key to be, in bytes.
96
97   block_size
98           $size = $cipher->block_size;
99
100       Get the block size, in bytes.
101
102   algorithm
103       Get the symmetric cipher algorithm.
104

METHODS

106   new
107   new_from_uuid
108   new_from_stream_id
109           $cipher = File::KDBX::Cipher->new(uuid => $uuid, key => $key, iv => $iv);
110           # OR
111           $cipher = File::KDBX::Cipher->new_from_uuid($uuid, key => $key, iv => $iv);
112
113           $cipher = File::KDBX::Cipher->new(stream_id => $id, key => $key);
114           # OR
115           $cipher = File::KDBX::Cipher->new_from_stream_id($id, key => $key);
116
117       Construct a new File::KDBX::Cipher.
118
119       This is a factory method which returns a subclass.
120
121   init
122           $self->init;
123
124       Called by "new" to set attributes. You normally shouldn't call this.
125       Returns itself to allow method chaining.
126
127   encrypt
128           $ciphertext = $cipher->encrypt($plaintext, ...);
129
130       Encrypt some data.
131
132   decrypt
133           $plaintext = $cipher->decrypt($ciphertext, ...);
134
135       Decrypt some data.
136
137   finish
138           $ciphertext .= $cipher->finish; # if encrypting
139           $plaintext  .= $cipher->finish; # if decrypting
140
141       Finish the stream.
142
143   encrypt_finish
144           $ciphertext = $cipher->encrypt_finish($plaintext, ...);
145
146       Encrypt and finish a stream in one call.
147
148   decrypt_finish
149           $plaintext = $cipher->decrypt_finish($ciphertext, ...);
150
151       Decrypt and finish a stream in one call.
152
153   register
154           File::KDBX::Cipher->register($uuid => $package, %args);
155
156       Register a cipher. Registered ciphers can be used to encrypt and
157       decrypt KDBX databases. A cipher's UUID must be unique and musn't
158       change. A cipher UUID is written into each KDBX file and the associated
159       cipher must be registered with the same UUID in order to decrypt the
160       KDBX file.
161
162       $package should be a Perl package relative to "File::KDBX::Cipher::" or
163       prefixed with a "+" if it is a fully-qualified package. %args are
164       passed as-is to the cipher's "init" method.
165
166   unregister
167           File::KDBX::Cipher->unregister($uuid);
168
169       Unregister a cipher. Unregistered ciphers can no longer be used to
170       encrypt and decrypt KDBX databases, until reregistered (see
171       "register").
172

BUGS

174       Please report any bugs or feature requests on the bugtracker website
175       <https://github.com/chazmcgarvey/File-KDBX/issues>
176
177       When submitting a bug or request, please include a test-file or a patch
178       to an existing test-file that illustrates the bug or desired feature.
179

AUTHOR

181       Charles McGarvey <ccm@cpan.org>
182

184       This software is copyright (c) 2022 by Charles McGarvey.
185
186       This is free software; you can redistribute it and/or modify it under
187       the same terms as the Perl 5 programming language system itself.
188
189
190
191perl v5.38.0                      2023-09-27             File::KDBX::Cipher(3)
Impressum