# 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:
      - Constant Field Values

  - ### KEY_PASSPHRASE

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

  - ### KEY_MANAGED

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

  - ### KEY_RAW

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

- ## 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, 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`: 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`