Class DatabaseConfig

java.lang.Object
com.codename1.db.DatabaseConfig
public final class DatabaseConfig extends Object

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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    KEY_MANAGED
    The key is random, generated once, and held in the platform key store.
    static final int
    KEY_NONE
    No encryption.
    static final int
    KEY_PASSPHRASE
    The key is derived from an application supplied passphrase.
    static final int
    KEY_RAW
    The key is 32 raw bytes supplied by the application.

  • Method Summary

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

    Methods inherited from class Object

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

  • Field Details

    • KEY_NONE

      public static final int KEY_NONE
      No encryption. The database is a plain SQLite file.
      See Also:

    • KEY_PASSPHRASE

      public static final int KEY_PASSPHRASE
      The key is derived from an application supplied passphrase.
      See Also:

    • KEY_MANAGED

      public static final int KEY_MANAGED
      The key is random, generated once, and held in the platform key store.
      See Also:

    • KEY_RAW

      public static final int KEY_RAW
      The key is 32 raw bytes supplied by the application.
      See Also:

  • 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: the secret, which must not be null or empty
      Returns

      a passphrase-keyed config

      Throws
      • IllegalArgumentException: if the passphrase is null or empty

    • 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: 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
      • #managed()

    • 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: 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: 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
      Throws:
      IOException