/*******************************************************************************
* Copyright (c) 2008 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.equinox.security.storage;
import java.io.IOException;
/**
* This interface describes functionality provided by secure preferences. Secure
* preferences can be used to persist sensitive information in an encrypted form.
* <p>
* Logically, secure preferences combine functionality of a keyring (keystore) and
* {@link org.osgi.service.prefs.Preferences}.
* </p><p>
* For an excellent detailed description of the preferences functionality see
* {@link org.osgi.service.prefs.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.
* </p><p>
* 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:
* </p>
* <pre>
* ISecurePreferences root = SecurePreferencesFactory.getDefault();
* ISecurePreferences node = root.node("cvs/eclipse.org");
* node.put("password", myPassword, true);
* </pre>
* <p>
* This interface has the following differences from the {@link org.osgi.service.prefs.Preferences}:
* <ul>
* <li>get...() and put...() methods throw StorageException</li>
* <li>put...() methods have an extra argument bEncrypt</li>
* <li>Methods that used to throw BackingStoreException will be throwing more detailed StorageException</li>
* <li>Navigation on preferences tree will return ISecurePreferences, as opposing to Preferences</li>
* <li>flush() throws IOException</li>
* <li>sync() method is removed</li>
* </ul>
* </p><p>
* 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.
* </p><p>
* It is worthwhile to reiterate that same limitations as {@link org.osgi.service.prefs.Preferences}
* apply to the node names. One non-trivial limitation is that node names can not contain forward
* slashes. For convenience, utility methods {@link EncodingUtils#encodeSlashes(String)} and
* {@link EncodingUtils#decodeSlashes(String)} are provided to work around this limitation.
* </p><p>
* 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.
* </p><p>
* If secure preferences were modified, the framework will automatically save them on shutdown.
* </p><p>
* This interface is not intended to be implemented or extended by clients.
* </p>
* @noextend This interface is not intended to be extended by clients.
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface ISecurePreferences {
/**
* Stores a value associated with the key in this node.
* @param key key with which the value is going to be associated
* @param value value to store
* @param encrypt <code>true</code> if value is to be encrypted, <code>false</code> value
* does not need to be encrypted
* @throws StorageException if exception occurred during encryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
* @throws NullPointerException if <code>key</code> is <code>null</code>.
*/
public void put(String key, String value, boolean encrypt) throws StorageException;
/**
* Retrieves a value associated with the key in this node. If the value was encrypted,
* it is decrypted.
* @param key key with this the value is associated
* @param def default value to return if the key is not associated with any value
* @return value associated the key. If value was stored in an encrypted form, it will be decrypted
* @throws StorageException if exception occurred during decryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public String get(String key, String def) throws StorageException;
/**
* Removes value associated with the key.
* @param key key with which a value is associated
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public void remove(String key);
/**
* Removes all values from this node.
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public void clear();
/**
* Returns keys that have associated values.
* @return keys that have associated values
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public String[] keys();
/**
* Returns names of children nodes
* @return names of children nodes
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public String[] childrenNames();
/**
* Returns parent of this node
* @return parent of this node
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public ISecurePreferences parent();
/**
* Returns node corresponding to the path specified. If such node does not
* exist, a new node is created.
* <p>
* If the node path is invalid, an {@link IllegalArgumentException} will be thrown
* by this method. The valid node path:
* <ul>
* <li>contains only ASCII characters between 32 and 126 (ASCII alphanumeric and printable
* characters);</li>
* <li>can not contain two or more consecutive forward slashes;</li>
* <li>can not end with a trailing forward slash.</li>
* </ul>
* </p>
* @see org.osgi.service.prefs.Preferences
* @see org.osgi.service.prefs.Preferences#node(String)
* @param pathName absolute or relative path to the node
* @return node corresponding to the path
* @throws IllegalArgumentException if the path name is invalid.
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public ISecurePreferences node(String pathName);
/**
* Checks if the node corresponding to the specified path exists in this tree
* of secure preferences.
* <p>
* If the node path is invalid, an {@link IllegalArgumentException} will be thrown
* by this method. See {@link #node(String)} for the description of what is considered
* to be a valid path.
* </p>
* @see org.osgi.service.prefs.Preferences
* @see org.osgi.service.prefs.Preferences#node(String)
* @param pathName absolute or relative path to the node
* @return <code>true</code> if node corresponding to the path exists, <code>false</code> otherwise
* @throws IllegalArgumentException if the path name is invalid.
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public boolean nodeExists(String pathName);
/**
* Removes this node from the tree of secure preferences.
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public void removeNode();
/**
* Returns name of this node.
* @return name of this node
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public String name();
/**
* Returns absolute path to this node.
* @return absolute path to this node
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public String absolutePath();
/**
* 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
*/
public void flush() throws IOException;
/**
* Stores a value associated with the key in this node.
* @param key key with which the value is going to be associated
* @param value value to store
* @param encrypt <code>true</code> if value is to be encrypted, <code>false</code> value
* does not need to be encrypted
* @throws StorageException if exception occurred during encryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
* @throws NullPointerException if <code>key</code> is <code>null</code>.
*/
public void putInt(String key, int value, boolean encrypt) throws StorageException;
/**
* Retrieves a value associated with the key in this node. If the value was encrypted,
* it is decrypted.
* @param key key with this the value is associated
* @param def default value to return if the key is not associated with any value
* @return value associated the key. If value was stored in an encrypted form, it will be decrypted
* @throws StorageException if exception occurred during decryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public int getInt(String key, int def) throws StorageException;
/**
* Stores a value associated with the key in this node.
* @param key key with which the value is going to be associated
* @param value value to store
* @param encrypt <code>true</code> if value is to be encrypted, <code>false</code> value
* does not need to be encrypted
* @throws StorageException if exception occurred during encryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
* @throws NullPointerException if <code>key</code> is <code>null</code>.
*/
public void putLong(String key, long value, boolean encrypt) throws StorageException;
/**
* Retrieves a value associated with the key in this node. If the value was encrypted,
* it is decrypted.
* @param key key with this the value is associated
* @param def default value to return if the key is not associated with any value
* @return value associated the key. If value was stored in an encrypted form, it will be decrypted
* @throws StorageException if exception occurred during decryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public long getLong(String key, long def) throws StorageException;
/**
* Stores a value associated with the key in this node.
* @param key key with which the value is going to be associated
* @param value value to store
* @param encrypt <code>true</code> if value is to be encrypted, <code>false</code> value
* does not need to be encrypted
* @throws StorageException if exception occurred during encryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
* @throws NullPointerException if <code>key</code> is <code>null</code>.
*/
public void putBoolean(String key, boolean value, boolean encrypt) throws StorageException;
/**
* Retrieves a value associated with the key in this node. If the value was encrypted,
* it is decrypted.
* @param key key with this the value is associated
* @param def default value to return if the key is not associated with any value
* @return value associated the key. If value was stored in an encrypted form, it will be decrypted
* @throws StorageException if exception occurred during decryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public boolean getBoolean(String key, boolean def) throws StorageException;
/**
* Stores a value associated with the key in this node.
* @param key key with which the value is going to be associated
* @param value value to store
* @param encrypt <code>true</code> if value is to be encrypted, <code>false</code> value
* does not need to be encrypted
* @throws StorageException if exception occurred during encryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
* @throws NullPointerException if <code>key</code> is <code>null</code>.
*/
public void putFloat(String key, float value, boolean encrypt) throws StorageException;
/**
* Retrieves a value associated with the key in this node. If the value was encrypted,
* it is decrypted.
* @param key key with this the value is associated
* @param def default value to return if the key is not associated with any value
* @return value associated the key. If value was stored in an encrypted form, it will be decrypted
* @throws StorageException if exception occurred during decryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public float getFloat(String key, float def) throws StorageException;
/**
* Stores a value associated with the key in this node.
* @param key key with which the value is going to be associated
* @param value value to store
* @param encrypt <code>true</code> if value is to be encrypted, <code>false</code> value
* does not need to be encrypted
* @throws StorageException if exception occurred during encryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
* @throws NullPointerException if <code>key</code> is <code>null</code>.
*/
public void putDouble(String key, double value, boolean encrypt) throws StorageException;
/**
* Retrieves a value associated with the key in this node. If the value was encrypted,
* it is decrypted.
* @param key key with this the value is associated
* @param def default value to return if the key is not associated with any value
* @return value associated the key. If value was stored in an encrypted form, it will be decrypted
* @throws StorageException if exception occurred during decryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public double getDouble(String key, double def) throws StorageException;
/**
* Stores a value associated with the key in this node.
* @param key key with which the value is going to be associated
* @param value value to store
* @param encrypt <code>true</code> if value is to be encrypted, <code>false</code> value
* does not need to be encrypted
* @throws StorageException if exception occurred during encryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
* @throws NullPointerException if <code>key</code> is <code>null</code>.
*/
public void putByteArray(String key, byte[] value, boolean encrypt) throws StorageException;
/**
* Retrieves a value associated with the key in this node. If the value was encrypted,
* it is decrypted.
* @param key key with this the value is associated
* @param def default value to return if the key is not associated with any value
* @return value associated the key. If value was stored in an encrypted form, it will be decrypted
* @throws StorageException if exception occurred during decryption
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public byte[] getByteArray(String key, byte[] def) throws StorageException;
/**
* Specifies if value associated with the key is encrypted.
* @param key key with which a value is associated
* @return <code>true</code> if value is encrypted, <code>false</code> otherwise
* @throws StorageException if stored data is invalid
* @throws IllegalStateException if this node (or an ancestor) has been removed with
* the {@link #removeNode()} method.
*/
public boolean isEncrypted(String key) throws StorageException;
}