KeePassJava2

master develop

A Java 8 API for databases compatible with the renowned KeePass password safe for Windows. This is a "headless" implementation - if you want something with a UI then KeePassXC and KeePassDX could be just the things for you.

Features to date:

• Read and write KeePass 2.x format (KDBX file formats V3 and V4)
• Keepass 2.x Password and Keyfile Credentials
• Read KeePass 1.x format (Rijndael only)
• No requirement for JCE Policy Files
• Android compatible
• Interfaces for Database, Group and Entry allow compatible addition of other formats

It is licensed under the Apache 2 License and is currently usable.

The work is provided on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties
or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY,
or FITNESS FOR A PARTICULAR PURPOSE.

You are solely responsible for determining the appropriateness
of using or redistributing the Work and assume any risks
associated with Your exercise of permissions under this License.

(see license)

Current Status

The current code is version 2.2.4 - released to Maven March 2025. This is on the main branch. See Build from Source

Key updates relative to 2.1:

• Java 8 (dependencies no longer support Java 7)
• File format version 4 support - with Argon2
• Inclusion of Jackson based KDBX support with a view to removing SimpleXML, JAXB and JAXB support
• Updated keyfile support
• Updated dependencies

See the changelog for more details.

Maven Coordinates

Release

The POM for the last release (2.2.4), Java 8 compatible, is

    <groupId>org.linguafranca.pwdb</groupId>
    <artifactId>KeePassJava2-jackson</artifactId>
    <version>2.2.4</version>

at Maven Central. This provides access to the Jackson based implementation, which is now the recommended implementation. There is also a composite POM that provides access to all implementations (see below for discussion).

    <groupId>org.linguafranca.pwdb</groupId>
    <artifactId>KeePassJava2</artifactId>
    <version>2.2.4</version>

Note that the artifactId has become Camel Case from release 2.1.x onwards.

Snapshot

Snapshot builds are erratically available at Sonatype, next bug-fix release will be 2.2.5-SNAPSHOT (on branch develop) and work-in-progress 3.0.0-SNAPSHOT (on branch v3):

    <groupId>org.linguafranca.pwdb</groupId>
    <artifactId>KeePassJava2</artifactId>
    <version>2.2.5-SNAPSHOT</version>

with appropriate <repositories> entry, like:

  <repositories>
     <repository>
       <id>oss.sonatype.org-snapshot</id>
       <url>https://central.sonatype.com/repository/maven-snapshots/</url>
       <releases>
         <enabled>false</enabled>
       </releases>
       <snapshots>
         <enabled>true</enabled>
       </snapshots>
     </repository>
   </repositories>

There are also separate POMs for the various modules. The module structure is illustrated below under Build from Source.

Java Version

From release 2.2 it requires Java 1.8. From release 3, Java 11. Earlier versions require Java 1.7.

Quick Start

Create credentials and an input stream for the password vault in question:

  KdbxCreds creds = new KdbxCreds("123".getBytes());
  InputStream inputStream = getClass().getClassLoader().getResourceAsStream("test1.kdbx");
  

then choose the Jackson based database implementation, and load the database

  Database database = JacksonDatabase.load(creds, inputStream)

See below for discussion of other database implementations. Note that they will not be maintained in the future - and see the following regarding making the storage of passwords more secure.

Storing Passwords

There are numerous well-understood problems with storing passwords as Strings in Java. See this discussion about the KeePassJava2 approach to storing passwords.

Available from release 2.2.3 the enhanced Jackson implementation is the only KeePassJava2 database implementation that provides a means of storing passwords other than as String.

Discussion

Password databases are modelled as a three layer abstraction.

A Database is a collection of records whose physical representation needs only to be capable of rendering as a stream. Entries hold the information of value in the database and Groups allow the structuring of entries into collections, just like a folder structure.

The Database has a root group and by following subgroups of the root group the tree structure of the database can be navigated. Entries belong to groups. Entries can be moved between groups and groups can also be moved between groups. However, entries and groups created in one database cannot be moved to another database without being converted:

database.newEntry(entryToCopy);
database.newGroup(groupToCopy);

The class Javadoc on Interface classes Database, Group and Entry describe how to use the methods of those classes to create and modify entries. These classes provide the basis of all implementations of the various database formats, initially KDB, KDBX 3.1 and KDBX 4 (KeePass 2) file formats, subsequently, potentially, others.

The class QuickStart.java provides some illustrations of operations using the Database, Group and Entry interfaces.

KeePassJava2 and KeePass

This project is so named by kind permission of Dominik Reichl the author of KeePass. There is no formal connection with that project.

It has always been the intention to support other specific password database implementations. Hence, the creation of abstract Database interfaces rather than following the KeePass model exactly.

KeePass is in effect defined by the code that Dominik writes to create and maintain the project and KDBX File Format Specification describes the file format. There is also a discussion of the differences between KDBX version 3.1 and version 4. Additionally, there is a discussion of the enhancements in KDBX 4.1, as well as a discussion of Key Files.

Massive credit also to the folks over at KeePassXC who wrote some documentation about their understanding of various format things. Also, this is a useful discussion/investigation of the KDBX format.

For the sake of clarification and my own satisfaction I have written about my understanding of KeePass formats in the following locations:

1. The Javadoc header to KdbxSerializer describes KDBX stream formatting.
2. The XSD Schema KDBX.4.xsd documents my understanding of the Keepass XML, and also my lack of understanding, in parts. While preparing release 2.2.3 I found this XSD at the KeePass site. I have not (so far) attempted to reconcile my documentation with it.
3. The following graphic illustrates KDBX 3.1 and 4 file formats:

Database Implementations

KeePass - or more specifically its file format KDBX - is an XML based format, so one of the main tasks is serializing and deserializing XML. Over time (KeePassJava2 was originally released in 2014) approaches to Java and XML have been a bit mysterious. However, Jackson has now been chosen as the underlying framework for implementation of KeePassJava2.

There are several other database implementations which will be maintained for bug-fix purposes only, with a view to being withdrawn, since they perform badly and/or depend on obsolete technology.

• SimpleXML - no longer maintained, does not work with Java 17 and up
• JAXB - this causes problems with javax and jakarta namespaces, it's not worth maintaining as it offers no compelling performance or other advantage
• DOM the was the original implementation and validates the fact that DOM based implementations are slow. That said, if you want to load a database and then save it while maintaining whatever quirks ex