com.sybase.persistence

Class DataVault

java.lang.Object

com.sybase.persistence.DataVault

Direct Known Subclasses:

PrivateDataVault, SharedDataVault

public abstract class DataVault
extends java.lang.Object

Top-level class of the DataVault library. An object of this type provides access to an encrypted storage. Being abstract, it comes with concrete implementations. One is SharedDataVault which uses a ContentProvider underneath, the other is PrivateDataVault which saves all data into a local SQLite database which is accessible only by the enclosing application.

Only the built-in implementations are supported. Clients may not (and actually can not) create their own subclasses of this type.

This class and the above subclasses have static lifecycle methods to manage data vault instances with. These can be used to initialize the library and the particular subclasses. Check out the related method documentations for the details.

The static methods of this class always delegate to SharedDataVault due to historical reasons. To use a PrivateDataVault, invoke its appropriate static methods.

A data vault may be either in a locked or an unlocked state. When unlocked, the data contents become accessible via the various setter and getter methods. If the data vault is locked then a password must be specified first before attempting to call any data access related methods. This can be done using unlock(char[]).

The password itself must adhere to a certain password policy, as described by an instance of DataVault.DVPasswordPolicy. This can be accessed using the getPasswordPolicy() and setPasswordPolicy(DVPasswordPolicy) methods. An important feature of the policy, apart from defining formal requirements that passwords must meet, is that it defines a lock timeout which if elapses the data vault locks itself.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DataVault.DVDataName This class represents a data record name (and type) within the DataVault that was stored by the application.
static class	DataVault.DVPasswordPolicy Represents the password policy that is used by various DataVault implementations to enforce certain rules on the configured passwords.

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	ERR_MSG_INVALID_PARAMETER
protected static java.lang.String	ERR_MSG_VAULT_DELETED
protected static java.lang.String	ERR_MSG_VAULT_EXISTS
protected java.lang.String	id The data vault identifier.
protected java.util.concurrent.locks.ReadWriteLock	lock Lock object to perform proper synchronization with.
protected static java.lang.String	LOG_TAG

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DataVault(java.lang.String id, boolean shouldExist, char[] password, com.sybase.persistence.ILegacyDataVault legacy, java.lang.String transformation, com.sybase.persistence.LowLevelStorage lowLevelStorage, com.sybase.persistence.EncryptionKeyDerivation preferredDerivation, com.sybase.persistence.EncryptionKeyDerivation... additionalDerivations) Creates a new data vault object.

Method Summary

Modifier and Type	Method and Description
void	changePassword(java.lang.String password, java.lang.String salt) Deprecated.
void	changePassword(java.lang.String currentPassword, java.lang.String currentSalt, java.lang.String newPassword, java.lang.String newSalt) Deprecated.
static DataVault	createVault(java.lang.String dataVaultId, char[] password) Creates a new shared data vault using SharedDataVault.createVault(String, char[]).
static DataVault	createVault(java.lang.String dataVaultId, java.lang.String password, java.lang.String salt) Deprecated.
byte[]	decrypt(byte[] cipherBytes) Decrypts an array of bytes that was previously encrypted by encrypt(byte[]).
void	decrypt(java.io.InputStream encryptedStream, java.io.OutputStream unencryptedStream, EncrypDecryptListener listener) Decrypts the data from the specified encrypted stream and writes it to the unencrypted one.
protected void	delete() Deletes this data vault.
void	deleteValue(java.lang.String name) Deletes the value pertaining to the specific name.
static void	deleteVault(java.lang.String dataVaultId) Deletes the shared vault using SharedDataVault.deleteVault(String).
byte[]	encrypt(byte[] plainBytes) Encrypts an array of bytes.
void	encrypt(java.io.InputStream unencryptedStream, java.io.OutputStream encryptedStream, EncrypDecryptListener listener) Encrypts the data coming from the specified stream and writes it to the output stream.
DataVault.DVDataName[]	getDataNames() Returns the data entry names and corresponding types.
int	getLockTimeout() Returns the lock timeout set.
DataVault.DVPasswordPolicy	getPasswordPolicy() Returns the password policy used by this data vault.
int	getRetryLimit() Returns the retry limit.
java.lang.String	getString(java.lang.String name) Returns the value set previously using setString(String, String).
byte[]	getValue(java.lang.String name) Returns the value set previously using setValue(String, byte[]).
static DataVault	getVault(java.lang.String dataVaultId) Returns an existing shared data vault using SharedDataVault.getVault(String).
static void	init(android.content.Context context) Performs initialization using SharedDataVault.init(Context).
boolean	isDefaultPasswordUsed() Returns if the default (i.e.
boolean	isLocked() Returns whether the data vault is locked.
void	lock() Locks this data vault.
void	modifyPassword(char[] password) Changes the password/salt of the vault.
void	modifyPassword(char[] currentPassword, char[] newPassword) Changes the password but performs an unlock operation beforehand, just like unlock(char[]) would.
void	resetLockTimeout() Resets the clock on the timeout feature, as if the user has just unlocked the vault.
void	setLockTimeout(int timeoutInSeconds) Sets the lock timeout.
void	setPasswordPolicy(DataVault.DVPasswordPolicy policy) Sets the password policy used by this data vault.
void	setRetryLimit(int limit) Sets the retry limit.
void	setString(java.lang.String name, java.lang.String value) Sets the specified key-string pair in the data vault.
void	setValue(java.lang.String name, byte[] value) Sets the specified key-binary pair in the data vault.
void	unlock(char[] password) Unlocks this data vault given the specified password.
void	unlock(java.lang.String password, java.lang.String salt) Does the same as unlock(char[]) but with an additional salt.
static boolean	vaultExists(java.lang.String dataVaultId) Checks shared data vault existence using SharedDataVault.vaultExists(String).

Methods inherited from class java.lang.Object

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

Field Detail

LOG_TAG

protected static final java.lang.String LOG_TAG

See Also:

Constant Field Values

ERR_MSG_VAULT_DELETED

protected static final java.lang.String ERR_MSG_VAULT_DELETED

See Also:

Constant Field Values

ERR_MSG_VAULT_EXISTS

protected static final java.lang.String ERR_MSG_VAULT_EXISTS

See Also:

Constant Field Values

ERR_MSG_INVALID_PARAMETER

protected static final java.lang.String ERR_MSG_INVALID_PARAMETER

See Also:

Constant Field Values

id

protected final java.lang.String id

The data vault identifier.

lock

protected final java.util.concurrent.locks.ReadWriteLock lock

Lock object to perform proper synchronization with.

Constructor Detail

DataVault

protected DataVault(java.lang.String id,
                    boolean shouldExist,
                    char[] password,
                    com.sybase.persistence.ILegacyDataVault legacy,
                    java.lang.String transformation,
                    com.sybase.persistence.LowLevelStorage lowLevelStorage,
                    com.sybase.persistence.EncryptionKeyDerivation preferredDerivation,
                    com.sybase.persistence.EncryptionKeyDerivation... additionalDerivations)

Creates a new data vault object. The legacy data vault, if specified, is stored only if it is present, as of ILegacyDataVault.isLegacyVaultPresent(). The derivation arguments are used to initialize the gatekeeper that controls the lifecycle of the data vault in terms of locking/unlocking. The low-level storage is responsible for managing how the data is actually stored. These two submodules should be using compatible encryption algorithms and transformations.

This constructor can create a new data vault from scratch or open an existing one, depending on what it finds in the underlying medium as of MetaInformation.checkProperExistence().

Parameters:

id - the data vault identifier, must be non-null

shouldExist - if true the vault should exist, if false it shouldn't

password - the password, used only for creation, can be null. If specified then it will be cleared after this call (no matter the outcome).

legacy - the legacy data vault to migrate away from at the next unlock, can be null

lowLevelStorage - the low-level storage which is bound to this data vault throughout its lifecycle, must be non-null

preferredDerivation - the preferred key derivation, must be non-null

additionalDerivations - the optional list of additional derivations to try

Throws:

DataVaultException - if any error occurs

Method Detail

init

public static void init(android.content.Context context)

Performs initialization using SharedDataVault.init(Context).

Parameters:

context - a context, must be non-null

createVault

public static DataVault createVault(java.lang.String dataVaultId,
                                    char[] password)

Creates a new shared data vault using SharedDataVault.createVault(String, char[]).

Parameters:

dataVaultId - the identifier of the new vault, must be non-null

password - password for encrypting the vault, must be non-null

Returns:

the freshly created data vault in unlocked state, always non-null

Throws:

DataVaultException - if the vault cannot be created

createVault

@Deprecated
public static DataVault createVault(java.lang.String dataVaultId,
                                                java.lang.String password,
                                                java.lang.String salt)

Deprecated.

Does the same thing as createVault(String, char[]). The salt parameter is ignored.

Parameters:

dataVaultId - the identifier of the new vault, must be non-null

password - password for encrypting the vault, must be non-null

salt - the salt, ignored

Returns:

the freshly created data vault in unlocked state, always non-null

Throws:

DataVaultException - if the vault cannot be created

getVault

public static DataVault getVault(java.lang.String dataVaultId)

Returns an existing shared data vault using SharedDataVault.getVault(String). Note that the returned object might be already in unlocked state. This can happen if a data vault has already been retrieved for this identifier.

This method always returns the same object for the same identifier.

Parameters:

dataVaultId - the data vault identifier, must be non-null

Returns:

the shared data vault, always non-null

Throws:

DataVaultException - if any error occurs during retrieval

deleteVault

public static void deleteVault(java.lang.String dataVaultId)

Deletes the shared vault using SharedDataVault.deleteVault(String).

Parameters:

dataVaultId - the data vault identifier, must be non-null

Throws:

DataVaultException - if any error occurs during removal

vaultExists

public static boolean vaultExists(java.lang.String dataVaultId)

Checks shared data vault existence using SharedDataVault.vaultExists(String).

Parameters:

dataVaultId - the data vault identifier, must be non-null

Throws:

DataVaultException - if any error occurs

unlock

public final void unlock(char[] password)

Unlocks this data vault given the specified password. Performs the migration without a salt from a legacy data vault, as necessary. Note that this might not succeed as the legacy data vault might itself require a salt. Use the overloaded (and deprecated) variant of this method in case you're sure the legacy data vault has been persisted with a salt.

Calling this method on a data vault that is already unlocked does not matter. The operation will execute either ways but if the password is incorrect then it will keep the vault unlocked if it was so already.

Parameters:

password - the password, can be null

Throws:

DataVaultException - if the password is incorrect or any other error occurs during the operation

unlock

public final void unlock(java.lang.String password,
                         java.lang.String salt)

Does the same as unlock(char[]) but with an additional salt. Newest implementations derive the salt internally. This method therefore needs to be used if the caller is sure that an older implementation is still present in persisted form. This method then will migrate away from that at the first successful unlock.

Parameters:

password - the password, can be null

salt - the salt, can be null

Throws:

DataVaultException - if the password and/or salt is incorrect or any other error occurs during the operation

lock

public final void lock()

Locks this data vault. Does nothing if the data vault has already been locked.

Throws:

DataVaultException - if the underlying data vault has already been deleted

isLocked

public final boolean isLocked()

Returns whether the data vault is locked.

Returns:

true if locked, false otherwise

Throws:

DataVaultException - if the underlying data vault has already been deleted

resetLockTimeout

public final void resetLockTimeout()

Resets the clock on the timeout feature, as if the user has just unlocked the vault.

Throws:

DataVaultException - if the underlying data vault has already been deleted or is in a locked state

modifyPassword

public final void modifyPassword(char[] password)

Changes the password/salt of the vault. This method must re-encrypt all values in the vault, so it should be called sparingly and patiently if the vault contains a lot of values.

Parameters:

password - the new password, can be null

Throws:

DataVaultException - if the underlying data vault has already been deleted or is in a locked state or the password is invalid

changePassword

@Deprecated
public final void changePassword(java.lang.String password,
                                             java.lang.String salt)

Deprecated.

Changes the password. In this version this method does the same thing as modifyPassword(char[]). Use that method instead.

Parameters:

password - the password, can be null

salt - the salt, unused in this version

Throws:

DataVaultException - if the underlying data vault has already been deleted or is in a locked state or the password is invalid

modifyPassword

public final void modifyPassword(char[] currentPassword,
                                 char[] newPassword)

Changes the password but performs an unlock operation beforehand, just like unlock(char[]) would.

Parameters:

currentPassword - the current password, can be null

newPassword - the new password, can be null

Throws:

DataVaultException - if the underlying data vault has already been deleted, the new password is not valid in terms of the policy or some other error occurs

changePassword

@Deprecated
public final void changePassword(java.lang.String currentPassword,
                                             java.lang.String currentSalt,
                                             java.lang.String newPassword,
                                             java.lang.String newSalt)

Deprecated.

Changes the password. It performs an unlock just like unlock(String, String) would. This implies that this method can be used if an underlying legacy data vault is expected to be still around.

Parameters:

currentPassword - the current password, can be null

currentSalt - the salt of the current password, can be null

newPassword - the new password, can be null

newSalt - the salt of the new password, unused in this version

Throws:

DataVaultException - if the underlying data vault has already been deleted, the new password is not valid in terms of the policy or some other error occurs

getPasswordPolicy

public final DataVault.DVPasswordPolicy getPasswordPolicy()

Returns the password policy used by this data vault. In the special case when this data vault has been created with a previous version of this library and this instance has not been unlocked yet then this method might throw a DataVaultException. This is because several fields of the password policy were stored with encryption in previous versions. In order to change this first an unlock needs to be performed.

Otherwise, if the data vault is locked then all the fields of the password policy are returned except for the expiration days and the lock timeout. If the data vault is unlocked then all fields are returned entirely.

Newly created data vaults will store the policy in the new unencrypted form right from the beginning so in their case the locked state matters only concerning a couple of fields, as described above.

Returns:

the policy, always non-null

Throws:

DataVaultException - if the data vault is locked and the policy is not yet present in an unencrypted representation

setPasswordPolicy

public final void setPasswordPolicy(DataVault.DVPasswordPolicy policy)

Sets the password policy used by this data vault. If the argument is null then the default policy is set.

The currently set password is not validated against this new policy as it is not possible without it. Therefore the incorrectness of the password can be detected the next time an attempt is made to unlock the vault with unlock(char[]), if the password does not adhere to the requirements of the new policy. The only way to remedy a situation like that is to modify the password using modifyPassword(char[], char[]) to a new one that is compliant with the newly set policy.

If the data vault is locked then the expiration days and the lock timeout fields are not persisted.

Note that if the policy is not stored in its new unencrypted representation (as documented by getPasswordPolicy() and this data vault is locked then this method throws a DataVaultException. In this case a successful unlock is required.

Parameters:

policy - the new policy, can be null

Throws:

DataVaultException - if the data vault is missing or the policy is invalid, as of DataVault.DVPasswordPolicy.validate()

isDefaultPasswordUsed

public final boolean isDefaultPasswordUsed()

Returns if the default (i.e. null) password can be used to unlock this vault. This method can be used at any time, even if there's an underlying legacy data vault that has not been migrated yet. If true is returned then the methods requiring the current password will be successful when parametrized with null.

Returns:

true if the default (=null) password is enough to open this store, false otherwise

setValue

public final void setValue(java.lang.String name,
                           byte[] value)

Sets the specified key-binary pair in the data vault.

Parameters:

name - the name of the key to set, must be non-null

value - the value or null if the association is to be deleted

Throws:

DataVaultException - if the data vault is locked or any other error occurs

getValue

public final byte[] getValue(java.lang.String name)

Returns the value set previously using setValue(String, byte[]).

Parameters:

name - the name of the key to get, must be non-null

Returns:

the value or null if it was not found

Throws:

DataVaultException - if the data vault is locked or any other error occurs

setString

public final void setString(java.lang.String name,
                            java.lang.String value)

Sets the specified key-string pair in the data vault.

Parameters:

name - the name of the key to set, must be non-null

value - the value or null if the association is to be deleted

Throws:

DataVaultException - if the data vault is locked or any other error occurs

getString

public final java.lang.String getString(java.lang.String name)

Returns the value set previously using setString(String, String).

Parameters:

name - the name of the key to get, must be non-null

Returns:

the value or null if it was not found

Throws:

DataVaultException - if the data vault is locked or any other error occurs

deleteValue

public final void deleteValue(java.lang.String name)

Deletes the value pertaining to the specific name. This is effectively the same as setting null using setValue(String, byte[]).

Parameters:

name - the name of the key to delete, must be non-null

Throws:

DataVaultException - if the data vault is locked or any other error occurs

getDataNames

public final DataVault.DVDataName[] getDataNames()

Returns the data entry names and corresponding types. The type is represented by an integer. The following type associations are possible:

• Unknown (0): The record is of unknown type. Best treat it as a simple raw byte array. It's possible only if the contents of this data vault have been persisted long ago with previous versions.
• String (2): The record is a string. The name can be used to access its value using getString(String).
• Binary (3): The record is a byte array. The name can be used to access its value using getValue(String).

The returned array is not backed by this object.

Returns:

the array of data names, always non-null

Throws:

DataVaultException - if the data vault is locked or any other error occurs

getLockTimeout

public final int getLockTimeout()

Returns the lock timeout set.

Returns:

the lock timeout in seconds

Throws:

DataVaultException - if the data vault is locked or any other error occurs

setLockTimeout

public void setLockTimeout(int timeoutInSeconds)

Sets the lock timeout.

Parameters:

timeoutInSeconds - the lock timeout in seconds to set, must be non-negative

Throws:

DataVaultException - if the data vault is locked or any other error occurs

getRetryLimit

public int getRetryLimit()

Returns the retry limit. This method can be called even in locked state.

Returns:

the retry limit

Throws:

DataVaultException - if any data access error occurs

setRetryLimit

public void setRetryLimit(int limit)

Sets the retry limit. This method can be called even in locked state.

Parameters:

limit - the retry limit to set, must be non-negative

Throws:

DataVaultException - if the data vault is locked or any other error occurs

encrypt

public final byte[] encrypt(byte[] plainBytes)

Encrypts an array of bytes. The data vault must be unlocked. The encryption is performed with an internally generated and stored secret key.

Parameters:

plainBytes - the bytes to encrypt, can be null

Returns:

the encrypted bytes, null if the input was null

Throws:

DataVaultException - if any error occurs during the operation

decrypt

public final byte[] decrypt(byte[] cipherBytes)

Decrypts an array of bytes that was previously encrypted by encrypt(byte[]). The data vault must be unlocked.

Parameters:

cipherBytes - the bytes to decrypt, can be null

Returns:

the decrypted bytes, null if the input was null

Throws:

DataVaultException - if any error occurs during the operation

encrypt

public final void encrypt(java.io.InputStream unencryptedStream,
                          java.io.OutputStream encryptedStream,
                          EncrypDecryptListener listener)
                   throws DataVaultException

Encrypts the data coming from the specified stream and writes it to the output stream. Encryption is done in chunks with each chunk being processed as encrypt(byte[]) would be called on it. Chunks are bytes long.

This method performs the operation on a separate thread and does not close neither of the streams.

Parameters:

unencryptedStream - the input, unencrypted stream, must be non-null

encryptedStream - the output stream to write encrypted data to, must be non-null

listener - the listener to invoke at the end of the operation, can be null

Throws:

DataVaultException - if any error occurs

decrypt

public final void decrypt(java.io.InputStream encryptedStream,
                          java.io.OutputStream unencryptedStream,
                          EncrypDecryptListener listener)
                   throws DataVaultException

Decrypts the data from the specified encrypted stream and writes it to the unencrypted one. The stream is expected to be formatted as if it were emitted by encrypt(InputStream, OutputStream, EncrypDecryptListener).

This method performs the operation on a separate thread and does not close neither of the streams.

Parameters:

encryptedStream - the encrypted stream to read from, must be non-null

unencryptedStream - the unencrypted stream to write to, must be non-null

listener - the listener to be notified at the end of the operation, can be null

Throws:

DataVaultException - if any error occurs

delete

protected final void delete()

Deletes this data vault. This object should be thrown away after a call to this method.