public final class DatabaseConfig

  1. Object
  2. DatabaseConfig

Describes how a database should be opened, and in particular how it is keyed.

Pass an instance to Database#openOrCreate(java.lang.String, com.codename1.db.DatabaseConfig). Opening without a config, through Database#openOrCreate(java.lang.String), is always plaintext and always will be – there is no implicit upgrade.

Security

A passphrase written into your source code is not a secret. String literals are recoverable from a shipped .ipa or .apk in minutes, so a constant passphrase buys you nothing against anyone who has the file. This is the mistake that gets made most often, so it is worth being blunt about it: if your application cannot ask a human for a passphrase, use #managed() instead. A random key held in the platform key store is strictly better than a constant compiled into the binary.

Encryption here protects data at rest and nothing else. It does not defend against a rooted or jailbroken device, a debugger attached to the running process, or a memory dump: while the database is open the key is in memory.

Choosing a mode

// A human supplies the secret. Nothing is stored on the device.
DatabaseConfig.passphrase(passwordField.getText());

// No secret to manage. A random key is generated once and kept in the
// platform key store. Best default when there is nobody to prompt.
DatabaseConfig.managed();

// The application already has 32 bytes of key material of its own.
DatabaseConfig.rawKey(keyBytes);

// Explicitly plaintext.
DatabaseConfig.plain();

On-disk format

Every platform that supports encryption reads and writes the same format, so a database created on one device can be opened on another and in the simulator. See the com.codename1.db package documentation for the pinned parameters.

Fields

public static final int KEY_NONE = 0No encryption.
public static final int KEY_PASSPHRASE = 1The key is derived from an application supplied passphrase.
public static final int KEY_MANAGED = 2The key is random, generated once, and held in the platform key store.
public static final int KEY_RAW = 3The key is 32 raw bytes supplied by the application.

Methods

public static DatabaseConfig plain()Returns a config that opens the database unencrypted.
public static DatabaseConfig passphrase(String passphrase)Returns a config keyed from the supplied passphrase.
public static DatabaseConfig managed()Returns a config keyed by a random key held in the platform key store, using the database name as the key alias.
public static DatabaseConfig managed(String keyAlias)Returns a config keyed by a random key held in the platform key store under an explicit alias.
public static DatabaseConfig rawKey(byte[] key)Returns a config keyed directly by 32 raw bytes, bypassing key derivation.
public int getKeyMode()Returns the key mode, one of #KEY_NONE, #KEY_PASSPHRASE, #KEY_MANAGED or #KEY_RAW.
public boolean isEncrypted()Returns whether this config asks for an encrypted database.
public String getKeyAlias()Returns the explicit managed key alias, or null when the database name is used as the alias.
public String getCipherProfile()Returns the cipher profile name that describes the on-disk format.
public boolean isKeyHardwareBacked()Returns whether keys for this config are protected by dedicated key storage hardware on the current platform.
public void wipe()Clears the key material held by this config.
public String resolveKeyMaterial(String databaseName) throws IOExceptionProduces the key literal handed to the underlying engine.

Inherited methods

From Object

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

Field details

KEY_NONE

public static final int KEY_NONE = 0
No encryption. The database is a plain SQLite file.

KEY_PASSPHRASE

public static final int KEY_PASSPHRASE = 1
The key is derived from an application supplied passphrase.

KEY_MANAGED

public static final int KEY_MANAGED = 2
The key is random, generated once, and held in the platform key store.

KEY_RAW

public static final int KEY_RAW = 3
The key is 32 raw bytes supplied by the application.

Method details

plain

public static DatabaseConfig plain()

Returns a config that opens the database unencrypted.

This is identical to calling Database#openOrCreate(java.lang.String) and exists so that code choosing between modes at runtime has something to return for the plaintext case.

Returns

a plaintext config

passphrase

public static DatabaseConfig passphrase(String passphrase)

Returns a config keyed from the supplied passphrase.

The passphrase is stretched into a key by the cipher’s key derivation function, so a weak passphrase yields a weak database. Nothing is stored on the device: losing the passphrase means losing the data.

Parameters

passphrase String
the secret, which must not be null or empty, and must not contain the character with code point zero

Returns

a passphrase-keyed config

Throws

IllegalArgumentException
if the passphrase is null, empty, or contains the character with code point zero

managed

public static DatabaseConfig managed()

Returns a config keyed by a random key held in the platform key store, using the database name as the key alias.

The first time a database is opened this way a fresh random key is generated and stored. Subsequent opens retrieve the same key. The application never sees or handles the key.

Durability

The key lives and dies with the platform key store entry. Uninstalling the application, wiping the device, or – on Android – restoring a backup onto a different device leaves the database permanently unreadable, because Android key store keys cannot be exported. iOS keychain entries do survive an encrypted backup and restore. If the data must outlive the device, use #passphrase(java.lang.String) with a secret the user or your server holds.

Returns

a config keyed from the platform key store

managed

public static DatabaseConfig managed(String keyAlias)

Returns a config keyed by a random key held in the platform key store under an explicit alias.

Use this when several databases should share one key, or when the database name may change but the key should not.

Parameters

keyAlias String
the key store alias, which must not be null or empty

Returns

a config keyed from the platform key store

Throws

IllegalArgumentException
if the alias is null or empty

See also

rawKey

public static DatabaseConfig rawKey(byte[] key)

Returns a config keyed directly by 32 raw bytes, bypassing key derivation.

Use this when the application already derives key material by its own means, for instance from a server-issued secret. Because no key derivation function is applied, the bytes must already be uniformly random – do not pass a hashed password here and expect passphrase-grade protection.

Parameters

key byte[]
exactly 32 bytes of key material

Returns

a raw-keyed config

Throws

IllegalArgumentException
if the array is null or is not exactly 32 bytes

getKeyMode

public int getKeyMode()
Returns the key mode, one of #KEY_NONE, #KEY_PASSPHRASE, #KEY_MANAGED or #KEY_RAW.

Returns

the key mode

isEncrypted

public boolean isEncrypted()
Returns whether this config asks for an encrypted database.

Returns

true unless the mode is #KEY_NONE

getKeyAlias

public String getKeyAlias()
Returns the explicit managed key alias, or null when the database name is used as the alias.

Returns

the alias or null

getCipherProfile

public String getCipherProfile()

Returns the cipher profile name that describes the on-disk format.

Only one profile is currently defined. The accessor exists so that a future profile can be introduced without changing the shape of this class.

Returns

the profile identifier

isKeyHardwareBacked

public boolean isKeyHardwareBacked()

Returns whether keys for this config are protected by dedicated key storage hardware on the current platform.

This is false for #passphrase(java.lang.String) and #rawKey(byte[]), because the application, not the platform, holds that key material. For #managed() it reflects the platform: true where a hardware backed key store is available, and false in the simulator, where the key is protected only by a software derived key in the desktop user profile.

Applications with a hard requirement on hardware backing should check this and refuse to store sensitive data when it returns false.

Returns

true when the key is held in hardware backed storage

wipe

public void wipe()

Clears the key material held by this config.

Call this once the database has been opened. The passphrase and raw key buffers are overwritten with zeroes.

Note the honest limitation: the value actually handed to the database engine is a String, because every supported engine keys from one, and Java strings are immutable and cannot be wiped. This method reduces the window, it does not eliminate it.

resolveKeyMaterial

public String resolveKeyMaterial(String databaseName) throws IOException

Produces the key literal handed to the underlying engine.

This exists for the platform implementations; applications have no reason to call it. Passphrases are returned verbatim. Raw and managed keys are rendered as the literal x' followed by 64 hexadecimal characters and a closing quote, which is the one form every supported engine interprets identically as a raw key with no key derivation applied.

For a managed key this is the call that generates and stores the key on first use, so it can fail even though the config itself was built successfully.

Parameters

databaseName String
used as the key store alias when no explicit alias was set

Returns

the key literal, or null when the config is plaintext

Throws

IOException
if a managed key could not be produced or stored