KeePassJava2

Java 17 API (from version 3.1.0 upwards) for password 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.1, V4 and V4.1)
• Keepass 2.x Password and Keyfile Credentials
• Pluggable memory storage and protection strategy
• Read KeePass 1.x format (KDB 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 3.1.0 - released to Maven October 2026. This is on branch v3-master, with development on branch v3-develop. See Build from Source. Upgrade to V3 requires minor changes to V2 code, see Upgrading from 2.x to 3.0 and Upgrading from 3.0 to 3.1.

Version 2 is still maintained for now, with bug and security fixes. Its current release is 2.2.6, on branch master, with development on branch develop.

Key updates relative to 2.x

• Java 11 (Java 17 from 3.1.0)
• Pluggable (protected) data storage model
• File format version 4 support - with Argon2
• Removal of SimpleXML, JAXB and DOM database implementations
• Removed generics on database classes
• Refactor modules and packages
• Updated keyfile support
• Updated dependencies

See the changelog for more details.

Upgrading from 2.x to 3.0

Upgrading from 2.x needs some, mostly minor, changes to your code and build:

• Java 11 is required (Java 17 from 3.1).

• One KDBX implementation. The Jackson implementation is now the KDBX database, KdbxDatabase (was JacksonDatabase). The Simple, JAXB and DOM implementations are removed.

• No generics on the database classes. Database, Group, Entry and so on are no longer generic, so declarations such as Database<?,?,?,?> become plain Database.

• Renamed classes, for example KdbxCreds is now KdbxCredentials.

• New artifacts (group org.linguafranca.pwdb):

  2.x	3.x
  KeePassJava2-jackson	KeePassJava2.kdbx.database
  KeePassJava2-kdbx	KeePassJava2.kdbx.io
  KeePassJava2-kdb	KeePassJava2.kdb
  database	database
  KeePassJava2 (all)	KeePassJava2 (KDBX and KDB)
  KeePassJava2-simple, -jaxb, -dom	removed

• New Java module names (issue 93), deliberately different from 2.x: org.linguafranca.pwdb.database, org.linguafranca.pwdb.kdb, org.linguafranca.pwdb.kdbx.io, org.linguafranca.pwdb.kdbx.database and org.linguafranca.pwdb.all. Update your requires clauses.

See the Quick Start for a worked example in the version 3 API.

Upgrading from 3.0 to 3.1

• Java 17 or later is required.

• Times on Entry and Group are java.time.Instant rather than java.util.Date. Where code needs a Date, convert at the call:

  Date created = Date.from(entry.getCreationTime());
  entry.setExpiryTime(expiryDate.toInstant());
  

• load and save are deprecated in favour of read and write, which leave the stream open, so close it yourself:

  try (InputStream inputStream = Files.newInputStream(path)) {
      database = KdbxDatabase.read(credentials, inputStream);
  }
  

Maven Coordinates

Release

The POM for the last release (3.1.0), Java 17 compatible, is

    <groupId>org.linguafranca.pwdb</groupId>
    <artifactId>KeePassJava2.kdbx.database</artifactId>
    <version>3.1.0</version>

at Maven Central. This provides access to the KDBX database implementation. There is also a composite POM that provides access to the KDBX and KDB implementations:

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

For the last 2.x release, see branch master.

Snapshot

Snapshot builds are published to the Maven Central snapshot repository, https://central.sonatype.com/repository/maven-snapshots/, which deletes them after about 90 days. The next release will be 3.2.0-SNAPSHOT (on branch v3-develop), not yet published:

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

with appropriate <repositories> entry, like:

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

The module structure is illustrated below under Build from Source.

Java Version

Versions 3.1.0 onwards require Java 17. Version 3.0.0 requires Java 11. From version 2.2 Java 1.8 is required. Earlier versions require Java 1.7.

Quick Start

Create credentials for the password vault in question, then read the database from an input stream:

  KdbxCredentials credentials = new KdbxCredentials("123".getBytes());
  Database database;
  try (InputStream inputStream = getClass().getClassLoader().getResourceAsStream("test1.kdbx")) {
      database = KdbxDatabase.read(credentials, inputStream);
  }

and write it to an output stream:

  try (OutputStream outputStream = Files.newOutputStream(Path.of("test1.kdbx"))) {
      database.write(credentials, outputStream);
  }

From 3.1.0 read and write leave the stream open, so whoever opens a stream closes it, as above. load and save, which close the stream they are given, are deprecated (see issue 109).

In the past there were a number of different database implementations, at present there are two, one for KDBX (KdbxDatabase - previously called JacksonDatabase, because it uses Jackson for XML serialization) and one to support the KeePass V2 KDB format (KdbDatabase).

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.

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, KDBX 3.1, 4 and 4.1 (KeePass 2) as well as KDB (KeePass 1), file formats.

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. While preparing release 2.2.3 I found this XSD at the KeePass site.

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.1.xsd documents my understanding of the Keepass XML, and also my lack of understanding, in parts.
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. From 3.0.0 a single KDBX implementation is available.

Aside from dependencies on underlying frameworks, different implementations have varying characteristics, primarily speed. This is assessed by this test in the module examples.

Dependencies

Aside from the JRE, at release 3.1.0, the API depends on:

• Google Guava (Apache 2 license).
• Apache Commons Codec (Apache 2 license).
• Bouncy Castle (MIT License).
• Jackson XML (Apache 2 license)
• Woodstox (Apache 2 license)

It also depends on SLF4J, logback and JUnit 5 for tests.

Build from Source

Included POM is for Maven 3.

It must be built using Java 17 or later (JDK 17+). It compiles with --release 17, so the jars it builds run on Java 17 whichever JDK builds them.

Module Structure

There are rather a lot of modules, this is in order to allow loading of minimal necessary functionality. The module dependencies are illustrated below.

Each module corresponds to a Maven artifact. The GroupId is org.linguafranca.pwdb. The version id is as noted above.

Module	ArtifactId	JavaDoc	Description
database	database		Base definition of the Database APIs.
example	(not published)	(not published)	Worked examples of loading, saving, splicing etc. using the APIs.
all	KeePassJava2		This is the main KeePassJava2 Maven dependency. Provides a route to all artifacts (other than test and examples) via transitive dependency.
kdb	KeePassJava2.kdb		An implementation of the Database APIs supporting KeePass KDB format.
kdbx-io	KeePassJava2.kdbx.io		Provides support for KDBX streaming and security.
kdbx-database	KeePassJava2.kdbx.database		Provides support for KDBX data access and memory protection.
basic	(not published)	(not published)	Experimental: a prototype database implementation, used for experimenting and testing. It may change or be removed.

Gradle

If you prefer Gradle the automatic conversion gradle init has been known to convert the POM successfully.

Change Log

In this file.

Acknowledgements

Many thanks to Pavel Ivanov @ivanovpv for his help with Android and Gradle compatibility issues back in the very early days.

Thanks to Giuseppe Valente @giusvale-dev for his contribution of the Jackson module and enhancements to KeyFile support.

Thanks to other contributors and raisers of issues.

License

Copyright (c) 2026 Jo Rabin

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.