PWDB :: Test

Contains the shared test classes for exercising the functionality of a PWDB database implementation.

License

License

GroupId

GroupId

org.linguafranca.pwdb
ArtifactId

ArtifactId

test
Last Version

Last Version

2.1.4
Release Date

Release Date

Type

Type

jar
Description

Description

PWDB :: Test
Contains the shared test classes for exercising the functionality of a PWDB database implementation.

Download test

How to add to project

<!-- https://jarcasting.com/artifacts/org.linguafranca.pwdb/test/ -->
<dependency>
    <groupId>org.linguafranca.pwdb</groupId>
    <artifactId>test</artifactId>
    <version>2.1.4</version>
</dependency>
// https://jarcasting.com/artifacts/org.linguafranca.pwdb/test/
implementation 'org.linguafranca.pwdb:test:2.1.4'
// https://jarcasting.com/artifacts/org.linguafranca.pwdb/test/
implementation ("org.linguafranca.pwdb:test:2.1.4")
'org.linguafranca.pwdb:test:jar:2.1.4'
<dependency org="org.linguafranca.pwdb" name="test" rev="2.1.4">
  <artifact name="test" type="jar" />
</dependency>
@Grapes(
@Grab(group='org.linguafranca.pwdb', module='test', version='2.1.4')
)
libraryDependencies += "org.linguafranca.pwdb" % "test" % "2.1.4"
[org.linguafranca.pwdb/test "2.1.4"]

Dependencies

compile (5)

Group / Artifact Type Version
org.linguafranca.pwdb : database jar 2.1.4
junit : junit jar 4.12
org.slf4j : slf4j-api jar 1.7.21
ch.qos.logback : logback-core jar 1.1.7
ch.qos.logback : logback-classic jar 1.1.7

Project Modules

There are no modules declared in this project.

KeePassJava2

Maven Central Master: Build Status Develop: Build Status

A Java 7 API for databases compatible with the renowned KeePass password safe for Windows.

Features to date:

  • Read and write KeePass 2.x format
  • 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)

Maven Coordinates

The composite POM is

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

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

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

Snapshot builds at Sonatype OSS.

Java Version

It is written for Java 1.7.

Quick Start

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

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

then choose a database implementation, and load the database.

  Database database = SimpleDatabase.load(credentials, inputStream)

or

  Database database = JaxbDatabase.load(credentials, inputStream)

or

  Database database = DomDatabaseWrapper.load(credentials, inputStream)

Different implementations have varying characteristics, primarily speed. The table below illustrates timings for the file test1.kdbx (in the test module resources - it is around 2k bytes and contains a few dozen entries) as assessed by this test in the examples module.

Simple 5 loads 20 iterations 257 millis
Jaxb 5 loads 20 iterations 326 millis
Dom 5 loads 20 iterations 758 millis

Simple 10 loads 1 iterations 340 millis
Jaxb 10 loads 1 iterations 552 millis
Dom 10 loads 1 iterations 175 millis

Simple 1 loads 50 iterations 28 millis
Jaxb 1 loads 50 iterations 47 millis
Dom 1 loads 50 iterations 251 millis

Load time is dominant in this example for JAXB and Simple, database traversal for the DOM implementation.

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 sub-groups 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 and KDBX 3.1 (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. Hence there is no definitive specification of KeePass files other than that code. 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 version 3.1 KDBX stream formatting.
  2. The XSD Schema KDBX.3.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: KDBX Formats

Dependencies

Aside from the JRE the API depends on:

The Simple XML implementation additionally depends on:

It also depends on SLF4J and Junit for tests.

Build from Source

Included POM is for Maven 3.

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.

Module Structure

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 Javadocs Base definition of the Database APIs.
example example Javadocs Worked examples of loading, saving, splicing etc. using the APIs
test test Javadocs Shared tests to assess the viability of the implementation.
all KeePassJava2 (no JavaDoc) This is the main KeePassJava2 Maven dependency. Provides a route to all artifacts (other than test and examples) via transitive dependency.
kdb KeePassJava2-kdb Javadocs An implementation of the Database APIs supporting KeePass KDB format.
kdbx KeePassJava2-kdbx Javadocs Provides support for KDBX streaming and security.
simple KeePassJava2-simple Javadocs A Simple XML Platform implementation of KDBX. Could be useful for Android.
jaxb KeePassJava2-jaxb Javadocs A JAXB implementation of KDBX. Probably not useful for Android. The generated class bindings might be useful for building other interfaces.
dom KeePassJava2-dom Javadocs A DOM based implementation of KDBX. Being DOM based it is rather slow, but messes less with existing content than the other two implementations. Known to work on Android.
http keepasshttp An implementation of a server intended to be the equivalent of keepasshttp, which is a plugin for Windows Keepass supporting communication with Chrome (chromeIPass) and Firefox(PassIFox) extensions.

It is experimental and usafe.

Please read and inwardly digest the readme.

Why are there so many implementations for KDBX? Well, the DOM implementation came first, because of the fact that it can load and save stuff that the implementation doesn't specifically know about. But it is very slow.

Then came the JAXB implementation, but belatedly it seems that Android support is in question. So latterly the Simple implementation. That's probably enough KDBX implementations.

Gradle

If you prefer Gradle the automatic conversion gradle init converts the POM successfully, however you will need to add something like gradle-source-sets.txt to the build.gradle for the JAXB module, so that the generated sources get compiled correctly.

Change Log

In this file.

Acknowledgements

Many thanks to Pavel Ivanov @ivanovpv for his help with Android and Gradle compatibility issues.

License

Copyright (c) 2016 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.

Versions

Version
2.1.4
2.1.3
2.1.1
2.1.0