KeePass2KeyRing

A Converter For KeePass Version 2.x to GNU KeyRing

by
David White
whitedavidp@fastmail.us

Introduction

I have been a user of GNU KeyRing, a password manager for the Palm OS for many years. I have also used a variety of desktop password managers and have always been irritated by my inability to synchronize data between the handheld and the desktop applications. Recently I switched my desktop application to KeePass and it is a great improvement over similar applications I have used.

Amazingly, someone had also created a KeePass port to J2ME which I can run on my handheld. But I quickly discovered that this was very limited so I remain wedded to KeyRing on that platform. Luckily, I found that there is a scripting plugin for Version 2.x of KeePass - KPScript which can be used from the Windows command line.

Between KeePass 2.x and KPScript, I perceived the opportunity to create an easy-to-use mechanism whereby I could convert my KeePass data into the KeyRing format. While this would not be a true 2-way synchronization between the programs, it was sufficiently valuable to be worth further investigation. The result is KeePass2KeyRing.

Credit To Whom It is Due

KeyPass2KeyRing is based almost entirely on KKConvert by Hugo Haas and, like KKConvert, uses code from KeyRing Editor which, in turn, is based upon Java Keyring by Frank Taylor. In comparison to everyone else, my contribution is minimal. We all stand on the shoulders of giants - thanks to all!

Requirements

KeePass2KeyRing is written in the Java programming language. As such, you will need to have a version of the Java SE Runtime Environment (JRE) installed on your computer. For reasons unclear to me at this time, older versions of the Java runtime do not support this program and result in an UnsupportedClassVersionError. So I recommend you use the latest version.

KeePass2KeyRing does not directly open a KeePass 2.x database. Instead it relies on the output of the ListEntries command from the KPScript plugin for KeePass version 2.x for its input. This greatly reduced the effort required. So you must download and install the KPScript addon. This consists of a single file, KPScript.exe, which simply must be placed in your KeePass 2.x installation folder.

Please note that KKConvert supports ONLY version 1.x of KeyRing. I am aware that a version 2.x beta version is available on the KeyRing SourceForge project site. But KeePass2KeyRing will not support it at any time in the near future.

Consistent with KKConvert, this program does not generate its own KeyRing database for output. Instead, you must supply one. KeePass2KeyRing will empty the contents of that database and then fills it with data from the KeePass database. All prior contents will be lost so use some care and work on a copy of that file (called Keys-Gtkr.pdb and generally found in the Backup folder in your desktop's palm data folder). Also note: I am informed by Justin Young, that the database supplied MUST contain at least one database entry otherwise an error occurs ("No real data").

Warning

This program comes with no warranty whatsoever. You are strongly advised to have a backup of your PDA data, and especially of your Keys-Gtkr.pdb before you run KeePass2KeyRing. If you have non-ASCII characters in your password database, there is a chance that the PDB generated will be corrupted, and that it will make your PDA reset. Or maybe your PDA's memory could be wiped out completely, though this should not happen.

Details

The conversion process goes something like this:

Run KPScript to perform its ListEntries command. KPScript will require, at minimum, the full path/name of your KeePass 2.x database and the password required to decrypt that database.
Run the KeePass2KeyRing converter to process the output from KPScript and update a valid KeyRing database such that it contains ONLY the data output from KPScript. To do this, KeePass2KeyRing requires the file containing the KPScript data, the path/name of the KeyRing database file, and the password requried to decrypt the KeyRing database file.
Synch the updated KeyRing database file to your handheld.

I have included an interactive Windows command script called KeePass2KeyRing.Simple.cmd that can greatly speed and simplify the process. This script works on my system and may have to be tweaked to work on yours. But the changes required should be limited to changing the names of folders, files, and paths in the script. I have tried to document it fully inside the command file itself.

One drawback of the KeePass2KeyRing.Simple.cmd script is that your KeePass data is stored on your disk in unencrypted form for a short period. In the event of an error, the script tries to remove this file as it will in the case of a successful conversion. In some cases, this cleanup may not occur properly and this constitutes a potential security risk. To prevent this, KeePass2KeyRing can be used in an alternate mode whereby it can accept the output of KPScript without requiring the use of a disk file and this eliminates the problem. But it does create some additional complexity in the Windows script. I have included an interactive Windows command script called KeePass2KeyRing.Complex.cmd which demonstrates this usage. Note that this script requires that you supply a parameter - your KeyRing database password.

Source Code

The .zip file I have supplied contains the source code required to compile KeePass2KeyRing should you wish to do so. You might want to do this for any of the following reasons (and more):

KeyRing's database is much less complex than that found in KeePass. Since there is no specific URL field, KeePass2KeyRing appends the KeePass URL (if any) to the KeePass Notes (if any) within the single, KeyRing notes field..
KeePass has a nice hierarchial way of grouping password entries. KeyRing, however, only supports 16 categories with names up to 16 characters in length. If KeePass2KeyRing enocunters any group names greater than 16 characters, it simply truncates it to the maximum length when creating a KeyRing category. Similarly, if KeePass2KeyRing encounters more than 16 categories, any entries found in categories beyond the 16th will be placed into the Unfiled category in KeyRing.
KeePass is often configured to maintain a Backup group. KeePass2KeyRing does not convert any entries in the Backup group - they are ignored.
KeePass 2.x can place entries in the root level of its organizing tree. It appears that such entries are given the special group name "Database". KeePass2KeyRing does not create a Database category in KeyRing and any such entries are placed into the Unfiled category in KeyRing.
KeePass supports nesting of password groups but KeePass2KeyRing makes no effort to support such nesting. While this might be do-able, KeyRing's limited category system makes this impractical. Therefore, KeePass2KeyRing will place entries from the following 2 group names into a single KeyRing category called Home: \Security\Home and \Banking\Home.

Download

You can download KeePass2KeyRing here.