Interface ISecurePreferences
Logically, secure preferences combine functionality of a keyring (keystore)
and Preferences
.
For an excellent detailed description of the preferences functionality see
Preferences
. To recap in a short form,
preferences provide a tree. Nodes on that tree can be used to specify
context. For instance, root node could have a child node called "cvs" to
store information related to CVS integration.
Each node can have a map of keys with associated values. For instance, to store password for the CVS repository located on eclipse.org we could use the following code:
ISecurePreferences root = SecurePreferencesFactory.getDefault(); ISecurePreferences node = root.node("cvs/eclipse.org"); node.put("password", myPassword, true);
This interface has the following differences from the
Preferences
:
- get...() and put...() methods throw StorageException
- put...() methods have an extra argument bEncrypt
- Methods that used to throw BackingStoreException will be throwing more detailed StorageException
- Navigation on preferences tree will return ISecurePreferences, as opposing to Preferences
- flush() throws IOException
- sync() method is removed
On the keyring side, when adding a key to the node, you can ask framework to encrypt it. Framework will lazily acquire password from password provider and use it to encrypt all new entries added to the secure preferences tree in this session.
It is worthwhile to reiterate that same limitations as
Preferences
apply to the node names. One
non-trivial limitation is that node names can not contain forward slashes.
For convenience, utility methods EncodingUtils.encodeSlashes(String)
and EncodingUtils.decodeSlashes(String)
are provided to work around
this limitation.
Also note that secure preferences only intended to store relatively small size data, such as passwords. If you need to securely store large objects, consider encrypting such objects in a symmetric way using randomly generated password and use secure preferences to store the password.
If secure preferences were modified, the framework will automatically save them on shutdown.
This interface is not intended to be implemented or extended by clients.
- Restriction:
- This interface is not intended to be implemented by clients.
- Restriction:
- This interface is not intended to be extended by clients.
-
Method Summary
Modifier and TypeMethodDescriptionReturns absolute path to this node.String[]
Returns names of children nodesvoid
clear()
Removes all values from this node.void
flush()
Saves the tree of secure preferences to the persistent storage.Retrieves a value associated with the key in this node.boolean
getBoolean
(String key, boolean def) Retrieves a value associated with the key in this node.byte[]
getByteArray
(String key, byte[] def) Retrieves a value associated with the key in this node.double
Retrieves a value associated with the key in this node.float
Retrieves a value associated with the key in this node.int
Retrieves a value associated with the key in this node.long
Retrieves a value associated with the key in this node.boolean
isEncrypted
(String key) Specifies if value associated with the key is encrypted.String[]
keys()
Returns keys that have associated values.name()
Returns name of this node.Returns node corresponding to the path specified.boolean
nodeExists
(String pathName) Checks if the node corresponding to the specified path exists in this tree of secure preferences.parent()
Returns parent of this nodevoid
Stores a value associated with the key in this node.void
putBoolean
(String key, boolean value, boolean encrypt) Stores a value associated with the key in this node.void
putByteArray
(String key, byte[] value, boolean encrypt) Stores a value associated with the key in this node.void
Stores a value associated with the key in this node.void
Stores a value associated with the key in this node.void
Stores a value associated with the key in this node.void
Stores a value associated with the key in this node.void
Removes value associated with the key.void
Removes this node from the tree of secure preferences.
-
Method Details
-
put
Stores a value associated with the key in this node.- Parameters:
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
-true
if value is to be encrypted,false
value does not need to be encrypted- Throws:
StorageException
- if exception occurred during encryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.NullPointerException
- ifkey
isnull
.
-
get
Retrieves a value associated with the key in this node. If the value was encrypted, it is decrypted.- Parameters:
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value- Returns:
- value associated the key. If value was stored in an encrypted form, it will be decrypted
- Throws:
StorageException
- if exception occurred during decryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
remove
Removes value associated with the key.- Parameters:
key
- key with which a value is associated- Throws:
IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
clear
void clear()Removes all values from this node.- Throws:
IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
keys
String[] keys()Returns keys that have associated values.- Returns:
- keys that have associated values
- Throws:
IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
childrenNames
String[] childrenNames()Returns names of children nodes- Returns:
- names of children nodes
- Throws:
IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
parent
ISecurePreferences parent()Returns parent of this node- Returns:
- parent of this node
- Throws:
IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
node
Returns node corresponding to the path specified. If such node does not exist, a new node is created.If the node path is invalid, an
IllegalArgumentException
will be thrown by this method. The valid node path:- contains only ASCII characters between 32 and 126 (ASCII alphanumeric and printable characters);
- can not contain two or more consecutive forward slashes;
- can not end with a trailing forward slash.
- Parameters:
pathName
- absolute or relative path to the node- Returns:
- node corresponding to the path
- Throws:
IllegalArgumentException
- if the path name is invalid.IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.- See Also:
-
nodeExists
Checks if the node corresponding to the specified path exists in this tree of secure preferences.If the node path is invalid, an
IllegalArgumentException
will be thrown by this method. Seenode(String)
for the description of what is considered to be a valid path.- Parameters:
pathName
- absolute or relative path to the node- Returns:
true
if node corresponding to the path exists,false
otherwise- Throws:
IllegalArgumentException
- if the path name is invalid.IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.- See Also:
-
removeNode
void removeNode()Removes this node from the tree of secure preferences.- Throws:
IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
name
String name()Returns name of this node.- Returns:
- name of this node
- Throws:
IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
absolutePath
String absolutePath()Returns absolute path to this node.- Returns:
- absolute path to this node
- Throws:
IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
flush
Saves the tree of secure preferences to the persistent storage. This method can be called on any node in the secure preference tree.- Throws:
IOException
- if error occurred while saving secure preferences
-
putInt
Stores a value associated with the key in this node.- Parameters:
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
-true
if value is to be encrypted,false
value does not need to be encrypted- Throws:
StorageException
- if exception occurred during encryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.NullPointerException
- ifkey
isnull
.
-
getInt
Retrieves a value associated with the key in this node. If the value was encrypted, it is decrypted.- Parameters:
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value- Returns:
- value associated the key. If value was stored in an encrypted form, it will be decrypted
- Throws:
StorageException
- if exception occurred during decryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
putLong
Stores a value associated with the key in this node.- Parameters:
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
-true
if value is to be encrypted,false
value does not need to be encrypted- Throws:
StorageException
- if exception occurred during encryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.NullPointerException
- ifkey
isnull
.
-
getLong
Retrieves a value associated with the key in this node. If the value was encrypted, it is decrypted.- Parameters:
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value- Returns:
- value associated the key. If value was stored in an encrypted form, it will be decrypted
- Throws:
StorageException
- if exception occurred during decryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
putBoolean
Stores a value associated with the key in this node.- Parameters:
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
-true
if value is to be encrypted,false
value does not need to be encrypted- Throws:
StorageException
- if exception occurred during encryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.NullPointerException
- ifkey
isnull
.
-
getBoolean
Retrieves a value associated with the key in this node. If the value was encrypted, it is decrypted.- Parameters:
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value- Returns:
- value associated the key. If value was stored in an encrypted form, it will be decrypted
- Throws:
StorageException
- if exception occurred during decryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
putFloat
Stores a value associated with the key in this node.- Parameters:
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
-true
if value is to be encrypted,false
value does not need to be encrypted- Throws:
StorageException
- if exception occurred during encryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.NullPointerException
- ifkey
isnull
.
-
getFloat
Retrieves a value associated with the key in this node. If the value was encrypted, it is decrypted.- Parameters:
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value- Returns:
- value associated the key. If value was stored in an encrypted form, it will be decrypted
- Throws:
StorageException
- if exception occurred during decryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
putDouble
Stores a value associated with the key in this node.- Parameters:
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
-true
if value is to be encrypted,false
value does not need to be encrypted- Throws:
StorageException
- if exception occurred during encryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.NullPointerException
- ifkey
isnull
.
-
getDouble
Retrieves a value associated with the key in this node. If the value was encrypted, it is decrypted.- Parameters:
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value- Returns:
- value associated the key. If value was stored in an encrypted form, it will be decrypted
- Throws:
StorageException
- if exception occurred during decryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
putByteArray
Stores a value associated with the key in this node.- Parameters:
key
- key with which the value is going to be associatedvalue
- value to storeencrypt
-true
if value is to be encrypted,false
value does not need to be encrypted- Throws:
StorageException
- if exception occurred during encryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.NullPointerException
- ifkey
isnull
.
-
getByteArray
Retrieves a value associated with the key in this node. If the value was encrypted, it is decrypted.- Parameters:
key
- key with this the value is associateddef
- default value to return if the key is not associated with any value- Returns:
- value associated the key. If value was stored in an encrypted form, it will be decrypted
- Throws:
StorageException
- if exception occurred during decryptionIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
isEncrypted
Specifies if value associated with the key is encrypted.- Parameters:
key
- key with which a value is associated- Returns:
true
if value is encrypted,false
otherwise- Throws:
StorageException
- if stored data is invalidIllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-