Secure your passwords with KeePass and Perl

These days password managers are an essential part of online security. The module File::KeePass provides an easy-to-use Perl API for the KeePass password manager and opens up a world-of-possibilities for programmatically creating, reading and updating passwords securely.


You’ll need to install File::KeePass. The CPAN testers results show that it runs on all modern Perls and many platforms including Windows. To install the module with CPAN, fire up the terminal and enter:

$ cpan File::KeePass

You may want to install KeePassX, an open source implementation of KeePass to get a GUI. I’ve used it on both Windows and Linux and it works great.

Creating KeePass Databases

The KeePass password manager stores all passwords in an encrypted database file. All username/password entries are stored in collections of entries called “groups”. File::KeePass provides for methods creating all of these items:

use File::KeePass;

my $kp_db = File::KeePass->new;

my $app_group = $kp_db->add_group({ title => 'Apps' });

$kp_db->add_entry({ title     => 'email',
                    username  => 'system',
                    password  => 'mumstheword',
                    group     => $app_group->{gid},

$kp_db->save_db('MyAppDetails.kdb', 'itsasecret');

In the code above we start by instantiating a new File::KeePass object. The “add_group” method adds a new group called “Apps” to the object. We then add an entry to the “Apps” group. The entry contains the username/password credentials that we want to store securely. Finally the “save_db” method saves the KeePass database to “MyAppDetails.kdb” (the extension is important) with a master password of “itsasecret” - in reality you would want to use a stronger password than this.

Save the code as “” and run it on the command line with this command:

$ perl

If you have KeePassX or KeePass installed, you can open the newly-created “MyAppDetails.kdb” file. When you do, you’ll be asked for the master password that we set:”

keepassx login

Once you’ve entered the master password, KeePassX will show the main window, which lists the groups and entries in the database file. You can see the “Apps” group on the left and the “email” entry that was created listed in the main window.

keepassx main screen

Reading KeePass databases

Instead of using a GUI like KeePass or KeePassX, you can read the contents of the database file using File::KeePass:

use File::KeePass;

my $kp_db = File::KeePass->new;
$kp_db->load_db('MyAppDetails.kdb', 'itsasecret');
my $groups = $kp_db->groups;

Here we opened our newly-created KeePass database file using the “load_db” method. The “groups” method returns an arrayref of groups. Each group is a hashref that also contains an arrayref of entries. Printing $groups with Data::Dumper, we can see this more clearly:”

$VAR1 = [
            'icon' => 0,
            'created' => '2014-03-24 08:28:44',
            'level' => 0,
            'entries' => [
                             'icon' => 0,
                             'modified' => '2014-03-24 08:28:44',
                             'username' => 'system',
                             'created' => '2014-03-24 08:28:44',
                             'comment' => '',
                             'url' => '',
                             'id' => 'E31rvRS5mqK37mak',
                             'title' => 'email',
                             'accessed' => '2014-03-24 08:28:44',
                             'expires' => '2999-12-31 23:23:59'
            'title' => 'Apps',
            'id' => 2450784255,
            'accessed' => '2014-03-24 08:28:44',
            'expires' => '2999-12-31 23:23:59',
            'modified' => '2014-03-24 08:28:44'

Searching and updating a KeePass database

File::KeePass provides methods for searching for entries. In order to update an entry, we have to retrieve it, update it, and then save the database file. Because entries are just hashrefs, this is easy:

use File::KeePass;

my $kp_db = File::KeePass->new;
$kp_db->load_db('MyAppDetails.kdb', 'itsasecret');
$kp_db->unlock; # enable changes

my $entry = $kp_db->find_entry({ title => 'email' }); 
$entry->{password} = 'mumsnottheword';

$kp_db->save_db('MyAppDetails.kdb', 'itsasecret');

In the code above we opened the database file, and used the “find_entry” method to search for our email entry. We then updated the password for the entry, and re-saved the database file. File::KeePass provides many additional methods for searching and updating groups and entries.


File::KeePass has a simple API that works great and comes with comprehensive documentation. I would recommend using the “.kdb” format as File::KeePass has open issues for the “.kdbx” format.

Enjoyed this article? Help us out and retweet it!

Cover image © DanielSTL

This article was originally posted on


David Farrell

David is a professional programmer who regularly tweets and blogs about code and the art of programming.

Browse their articles


Something wrong with this article? Help us out by opening an issue or pull request on GitHub