org.linguafranca.pwdb.kdbx

Class KdbxSerializer

java.lang.Object

org.linguafranca.pwdb.kdbx.KdbxSerializer

public class KdbxSerializer
extends Object

This class provides static methods for the encryption and decryption of Keepass KDBX V3 and V4 files.

KDBX files are little-endian and consist of the following:

1. An unencrypted portion
2. 1. 8 bytes Magic number
   2. 4 bytes version
   3. A header containing details of the encryption of the remainder of the file:

      The header fields are encoded using a TLV style. The Type is an enumeration encoded in 1 byte. The length is encoded in 4 bytes (V3: 2 bytes) and the value according to the length denoted. The sequence is terminated by a zero type with 0 length. readOuterHeader(java.io.InputStream, org.linguafranca.pwdb.kdbx.KdbxHeader)

      In V4 there follows a 32 byte SHA-256 hash of the file so far

      In V4 there follows a 32 byte HMAC-256 hash of the file so far

      KdbxHeader details the fields of the header.

3. In V3 the remainder of the file is encrypted as follows:
4. 1. A sequence of bytes contained in the header. If they don't match, decryption has not worked.
   2. A payload serialized in Hashed Block format, see e.g. HashedBlockInputStream for details of this.
   3. The content of this payload may be GZIP compressed.
   4. The content is now a character stream, which is expected to be XML representing a KeePass Database. Assumed UTF-8 encoding.
5. In V4 the remainder of the file is encoded as HMacBlocks:
6. 1. A sequence of blocks encoded using Hmac Blocks see HmacBlockInputStream
   2. Those blocks contain an encrypted input stream.
   3. The encrypted input stream optionally contains a Gzipped input stream.
   4. The content is now a character stream, which is an inner header readInnerHeader(org.linguafranca.pwdb.kdbx.KdbxHeader, java.io.InputStream) followed by XML representing a KeePass Database. Assumed UTF-8 encoding.

The methods in this class provide support for serializing and deserializing plain text payload content to and from the above encrypted format.

Various fields of the plain text XML (e.g. passwords) are additionally and optionally encrypted using a second encryption. They are stream encrypted, meaning they have to be decrypted in the same order as they were encrypted, namely actual XML document order. Or at least that is the way it seems. The methods of this class do not perform this aspect of encryption/decryption.

Author:

jo

See Also:

this diagram

Method Summary

Modifier and Type	Method and Description
static OutputStream	createEncryptedOutputStream(Credentials credentials, KdbxHeader kdbxHeader, OutputStream outputStream) Provides an OutputStream to be encoded and encrypted in KDBX format
static InputStream	createUnencryptedInputStream(Credentials credentials, KdbxHeader kdbxHeader, InputStream inputStream) Provides the payload of a KDBX file as an unencrypted InputStream.
static KdbxHeader	readOuterHeader(InputStream inputStream, KdbxHeader kdbxHeader) Create and populate a KdbxHeader from the input stream supplied
static void	readOuterHeaderVerification(KdbxHeader kdbxHeader, Credentials credentials, DataInput input) V4 header is followed by an SHA256 and then contains an HMAC SHA256 after that.
static VariantDictionary	readVariantDictionary(byte[] source) Read a VariantDictionary from the supplied input according to KDBX rules
static byte[]	serializeVariantDictionary(VariantDictionary v) Serialize a variant dictionary according to KDBX rules
static void	writeInnerHeader(KdbxHeader kdbxHeader, OutputStream outputStream)
static void	writeKdbxHeader(KdbxHeader kdbxHeader, OutputStream outputStream) Write a KdbxHeader to the output stream supplied.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createUnencryptedInputStream

public static InputStream createUnencryptedInputStream(Credentials credentials,
                                                       KdbxHeader kdbxHeader,
                                                       InputStream inputStream)
                                                throws IOException

Provides the payload of a KDBX file as an unencrypted InputStream.

Parameters:

credentials - credentials for decryption of the stream

kdbxHeader - a KdbxHeader for the encryption parameters and so on

inputStream - a KDBX formatted input stream

Returns:

an unencrypted input stream, to be read and closed by the caller

Throws:

IOException - on error

createEncryptedOutputStream

public static OutputStream createEncryptedOutputStream(Credentials credentials,
                                                       KdbxHeader kdbxHeader,
                                                       OutputStream outputStream)
                                                throws IOException

Provides an OutputStream to be encoded and encrypted in KDBX format

Parameters:

credentials - credentials for encryption of the stream

kdbxHeader - a KDBX header to control the formatting and encryption operation

outputStream - output stream to contain the KDBX formatted output

Returns:

an unencrypted output stream, to be written to, flushed and closed by the caller

Throws:

IOException - on error

readOuterHeader

public static KdbxHeader readOuterHeader(InputStream inputStream,
                                         KdbxHeader kdbxHeader)
                                  throws IOException

Create and populate a KdbxHeader from the input stream supplied

Parameters:

inputStream - an input stream

Returns:

the populated KdbxHeader

Throws:

IOException - on error

readOuterHeaderVerification

public static void readOuterHeaderVerification(KdbxHeader kdbxHeader,
                                               Credentials credentials,
                                               DataInput input)
                                        throws IOException

V4 header is followed by an SHA256 and then contains an HMAC SHA256 after that.

Parameters:

kdbxHeader - the header containing the relevant parameters

credentials - the credentials - used to verify the HMAC

input - an input source

Throws:

IOException - on error

writeKdbxHeader

public static void writeKdbxHeader(KdbxHeader kdbxHeader,
                                   OutputStream outputStream)
                            throws IOException

Write a KdbxHeader to the output stream supplied. The header is updated with the message digest of the written stream.

Parameters:

kdbxHeader - the header to write and update

Throws:

IOException - on error

writeInnerHeader

public static void writeInnerHeader(KdbxHeader kdbxHeader,
                                    OutputStream outputStream)
                             throws IOException

Throws:

IOException

readVariantDictionary

public static VariantDictionary readVariantDictionary(byte[] source)

Read a VariantDictionary from the supplied input according to KDBX rules

Parameters:

source - source of data

Returns:

a VariantDictionary

serializeVariantDictionary

public static byte[] serializeVariantDictionary(VariantDictionary v)

Serialize a variant dictionary according to KDBX rules

Parameters:

v - the dictionary to serialize

Returns:

a byte array