---
name: "File::KDBX::Cipher"
section: "3pm"
platform: "linux"
package: "libfile-kdbx-perl"
version: "0.906-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/File::KDBX::Cipher"
---

# File::KDBX::Cipher(3pm)

A block cipher mode or cipher stream

## 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.