Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com
Answertopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 


Eclipse Platform
Release 3.5

org.eclipse.equinox.security.storage
Interface ISecurePreferences


public interface ISecurePreferences

This interface describes functionality provided by secure preferences. Secure preferences can be used to persist sensitive information in an encrypted form.

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
  String absolutePath ()
          Returns absolute path to this node.
  String[] childrenNames ()
          Returns names of children nodes
 void clear ()
          Removes all values from this node.
 void flush ()
          Saves the tree of secure preferences to the persistent storage.
  String get ( String key, String def)
          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 getDouble ( String key, double def)
          Retrieves a value associated with the key in this node.
 float getFloat ( String key, float def)
          Retrieves a value associated with the key in this node.
 int getInt ( String key, int def)
          Retrieves a value associated with the key in this node.
 long getLong ( String key, long def)
          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.
  String name ()
          Returns name of this node.
  ISecurePreferences node ( String pathName)
          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.
  ISecurePreferences parent ()
          Returns parent of this node
 void put ( String key, String value, boolean encrypt)
          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 putDouble ( String key, double value, boolean encrypt)
          Stores a value associated with the key in this node.
 void putFloat ( String key, float value, boolean encrypt)
          Stores a value associated with the key in this node.
 void putInt ( String key, int value, boolean encrypt)
          Stores a value associated with the key in this node.
 void putLong ( String key, long value, boolean encrypt)
          Stores a value associated with the key in this node.
 void remove ( String key)
          Removes value associated with the key.
 void removeNode ()
          Removes this node from the tree of secure preferences.
 

Method Detail

put

void put(
String key,
         
String value,
         boolean encrypt)
         throws 
StorageException
Stores a value associated with the key in this node.

Parameters:
key - key with which the value is going to be associated
value - value to store
encrypt - true if value is to be encrypted, false value does not need to be encrypted
Throws:
StorageException - if exception occurred during encryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.
NullPointerException - if key is null.

get


String get(
String key,
           
String def)
           throws 
StorageException
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 associated
def - 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 decryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.

remove

void remove(
String key)
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 the removeNode() method.

clear

void clear()
Removes all values from this node.

Throws:
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() 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 the removeNode() 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 the removeNode() 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 the removeNode() method.

node


ISecurePreferences node(
String pathName)
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 the removeNode() method.
See Also:
Preferences , Preferences.node(String)

nodeExists

boolean nodeExists(
String pathName)
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. See node(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 the removeNode() method.
See Also:
Preferences , Preferences.node(String)

removeNode

void removeNode()
Removes this node from the tree of secure preferences.

Throws:
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() 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 the removeNode() 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 the removeNode() method.

flush

void flush()
           throws 
IOException
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

void putInt(
String key,
            int value,
            boolean encrypt)
            throws 
StorageException
Stores a value associated with the key in this node.

Parameters:
key - key with which the value is going to be associated
value - value to store
encrypt - true if value is to be encrypted, false value does not need to be encrypted
Throws:
StorageException - if exception occurred during encryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.
NullPointerException - if key is null.

getInt

int getInt(
String key,
           int def)
           throws 
StorageException
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 associated
def - 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 decryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.

putLong

void putLong(
String key,
             long value,
             boolean encrypt)
             throws 
StorageException
Stores a value associated with the key in this node.

Parameters:
key - key with which the value is going to be associated
value - value to store
encrypt - true if value is to be encrypted, false value does not need to be encrypted
Throws:
StorageException - if exception occurred during encryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.
NullPointerException - if key is null.

getLong

long getLong(
String key,
             long def)
             throws 
StorageException
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 associated
def - 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 decryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.

putBoolean

void putBoolean(
String key,
                boolean value,
                boolean encrypt)
                throws 
StorageException
Stores a value associated with the key in this node.

Parameters:
key - key with which the value is going to be associated
value - value to store
encrypt - true if value is to be encrypted, false value does not need to be encrypted
Throws:
StorageException - if exception occurred during encryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.
NullPointerException - if key is null.

getBoolean

boolean getBoolean(
String key,
                   boolean def)
                   throws 
StorageException
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 associated
def - 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 decryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.

putFloat

void putFloat(
String key,
              float value,
              boolean encrypt)
              throws 
StorageException
Stores a value associated with the key in this node.

Parameters:
key - key with which the value is going to be associated
value - value to store
encrypt - true if value is to be encrypted, false value does not need to be encrypted
Throws:
StorageException - if exception occurred during encryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.
NullPointerException - if key is null.

getFloat

float getFloat(
String key,
               float def)
               throws 
StorageException
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 associated
def - 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 decryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.

putDouble

void putDouble(
String key,
               double value,
               boolean encrypt)
               throws 
StorageException
Stores a value associated with the key in this node.

Parameters:
key - key with which the value is going to be associated
value - value to store
encrypt - true if value is to be encrypted, false value does not need to be encrypted
Throws:
StorageException - if exception occurred during encryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.
NullPointerException - if key is null.

getDouble

double getDouble(
String key,
                 double def)
                 throws 
StorageException
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 associated
def - 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 decryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.

putByteArray

void putByteArray(
String key,
                  byte[] value,
                  boolean encrypt)
                  throws 
StorageException
Stores a value associated with the key in this node.

Parameters:
key - key with which the value is going to be associated
value - value to store
encrypt - true if value is to be encrypted, false value does not need to be encrypted
Throws:
StorageException - if exception occurred during encryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.
NullPointerException - if key is null.

getByteArray

byte[] getByteArray(
String key,
                    byte[] def)
                    throws 
StorageException
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 associated
def - 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 decryption
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.

isEncrypted

boolean isEncrypted(
String key)
                    throws 
StorageException
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 invalid
IllegalStateException - if this node (or an ancestor) has been removed with the removeNode() method.

Eclipse Platform
Release 3.5

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire