From a logical perspective secure storage represents a hybrid of OSGi's Preferences and a keyring.
The front end is modeled in a fashion very similar to the OSGi Preferences Service specification. Secure storage is represented as a tree of nodes. Nodes provide context. For instance, a bundle "com.abc" could use the node "abc" under the node "com" under the root node. As in Preference's, the path to such node can be described as "/com/abc".
Picture 1. How the data is organized.
The data is stored under the node as a key-value pair. The data can be stored in an encrypted form or as a clear text. The ability to store clear-text data is provided so that logically related information (such as non-encrypted user name and encrypted password) can be stored using the same mechanism.
The code to store a password associated with "com.abc" could look like this:
...
ISecurePreferences root = SecurePreferencesFactory.getDefault();
ISecurePreferences node = root.node("/com/abc");
node.put("password", "12345", true /*encrypt*/);
...
and then to retrieve the data:
...
String password = node.get("password", null /*default*/);
...
If secure storage was modified, it will be saved when the application is closed. Alternatively, a save can be triggered programmatically by calling ISecurePreferences#flush().
On the back end, secure storage can be thought of as a keyring. Each entry is associated with a password provider; only this password provider can be used in the future to decrypt the entry.
Picture 2. Relationship between entries and password providers.
Secure storage has provisions to obtain the master password from various sources described by password providers. Even more importantly for developers, the set of password providers is open and easily customizable.