Package org.freedesktop.secret.simple

Class SimpleCollection

java.lang.Object

org.freedesktop.secret.simple.interfaces.SimpleCollection

org.freedesktop.secret.simple.SimpleCollection

All Implemented Interfaces:

AutoCloseable

public final class SimpleCollection
extends SimpleCollection

Constructor Summary

Constructors

Constructor	Description
SimpleCollection()	The default collection.
SimpleCollection(String label, CharSequence password)	A user specified collection.

Method Summary

Modifier and Type	Method	Description
void	clear()	Clears the private key of the transport encryption and the passphrase of the collection.
void	close()
String	createItem(String label, CharSequence password)	Creates an item with the provided properties in this collection.
String	createItem(String label, CharSequence password, Map<String,String> attributes)	Creates an item with the provided properties in this collection.
void	delete()	Delete this collection.
void	deleteItem(String objectPath)	Delete an item from this collection.
void	deleteItems(List<String> objectPaths)	Delete specified items from this collection.
static boolean	disconnect()	Close the DBus connection immediately.
Map<String,String>	getAttributes(String objectPath)	Get the user specified attributes of an item.
List<String>	getItems(Map<String,String> attributes)	Get the object paths of items with given attributes.
String	getLabel(String objectPath)	Get the displayable label of an item.
char[]	getSecret(String objectPath)	Get the secret of the item.
Map<String,char[]>	getSecrets()	Get the secrets from this collection.
Duration	getTimeout()
static boolean	isAvailable()	Checks if all services are provided by the system: org.freedesktop.DBus org.freedesktop.secrets org.gnome.keyring
static boolean	isConnected()	Checks the D-Bus connection status.
boolean	isLocked()
void	lock()
void	setTimeout(Duration timeout)
void	unlockWithUserPermission()	Locks and unlocks the default collection explicitly.
void	updateItem(String objectPath, String label, CharSequence password, Map<String,String> attributes)	Updates an item with the provided properties.

Methods inherited from class java.lang.Object

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

Constructor Details

SimpleCollection

public SimpleCollection() throws IOException

The default collection.

Throws:

IOException - Could not communicate properly with the DBus. Check the logs.

SimpleCollection

public SimpleCollection(String label, CharSequence password) throws IOException

A user specified collection.

Parameters:

label - The displayable label of the collection

NOTE: The label of a collection may differ from the id of a collection. The id is assigned by the Secret Service and used in the DBus object path of a collection or item.

The SimpleCollection can't handle collections with the same label, but different ids correctly, as the id is inferred by the given label.

password - Password of the collection

Throws:

IOException - Could not communicate properly with the DBus. Check the logs.

Method Details

isConnected

public static boolean isConnected()

Checks the D-Bus connection status.

Returns:

true if connected to the D-Bus, otherwise false

isAvailable

public static boolean isAvailable()

Checks if all services are provided by the system:
org.freedesktop.DBus
org.freedesktop.secrets
org.gnome.keyring

Returns:

true if the secret service is available, otherwise false and will log an error message.

disconnect

public static boolean disconnect()

Close the DBus connection immediately. Waits for the DBus connection to close within 2 seconds.

lock

public void lock()

Specified by:

lock in class SimpleCollection

unlockWithUserPermission

public void unlockWithUserPermission() throws AccessControlException

Locks and unlocks the default collection explicitly.

The default collection gets only locked on the first call of a session.

Once the default collection is unlocked the user will not be prompted again as long as the default collection stays unlocked.

This method is used to enforce user interaction for:

getSecrets()

deleteItem(String)

deleteItems(List)

Specified by:

unlockWithUserPermission in class SimpleCollection

Throws:

AccessControlException - if the user does not provide the correct credentials.

clear

public void clear()

Clears the private key of the transport encryption and the passphrase of the collection.

Specified by:

clear in class SimpleCollection

close

public void close()

Specified by:

close in interface AutoCloseable

Specified by:

close in class SimpleCollection

delete

public void delete() throws AccessControlException

Delete this collection.

Specified by:

delete in class SimpleCollection

Throws:

AccessControlException

createItem

public String createItem(String label, CharSequence password, Map<String,String> attributes) throws IllegalArgumentException

Creates an item with the provided properties in this collection.

Specified by:

createItem in class SimpleCollection

Parameters:

label - The displayable label of the new item

password - The password of the new item

attributes - The attributes of the new item

Returns:

DBus object path or null

Throws:

IllegalArgumentException - The label and password are non-nullable.

createItem

public String createItem(String label, CharSequence password) throws IllegalArgumentException

Creates an item with the provided properties in this collection.

Specified by:

createItem in class SimpleCollection

Parameters:

label - The displayable label of the new item

password - The password of the new item

Returns:

DBus object path

Throws:

IllegalArgumentException - The label and password are non-nullable.

updateItem

public void updateItem(String objectPath, String label, CharSequence password, Map<String,String> attributes) throws IllegalArgumentException

Updates an item with the provided properties.

Specified by:

updateItem in class SimpleCollection

Parameters:

objectPath - The DBus object path of the item

label - The displayable label of the new item

password - The password of the new item

attributes - The attributes of the new item

Throws:

IllegalArgumentException - The object path, label and password are non-nullable.

getLabel

public String getLabel(String objectPath)

Get the displayable label of an item.

Specified by:

getLabel in class SimpleCollection

Parameters:

objectPath - The DBus object path of the item

Returns:

label or null

getAttributes

public Map<String,String> getAttributes(String objectPath)

Get the user specified attributes of an item.

The attributes can contain an additional xdg:schema key-value pair.

Specified by:

getAttributes in class SimpleCollection

Parameters:

objectPath - The DBus object path of the item

Returns:

item attributes or null

getItems

public List<String> getItems(Map<String,String> attributes)

Get the object paths of items with given attributes.

Specified by:

getItems in class SimpleCollection

Parameters:

attributes - The attributes of the secret

Returns:

object paths or null

getSecret

public char[] getSecret(String objectPath)

Get the secret of the item.

Specified by:

getSecret in class SimpleCollection

Parameters:

objectPath - The DBus object path of the item

Returns:

plain chars or null

getSecrets

public Map<String,char[]> getSecrets() throws AccessControlException

Get the secrets from this collection.

Retrieving all passwords form the default collection requires user permission.

see: unlockWithUserPermission()

Specified by:

getSecrets in class SimpleCollection

Returns:

Mapping of DBus object paths and plain chars or null

Throws:

AccessControlException

deleteItem

public void deleteItem(String objectPath) throws AccessControlException

Delete an item from this collection.

Deleting a password form the default collection requires user permission.

see: unlockWithUserPermission()

Specified by:

deleteItem in class SimpleCollection

Parameters:

objectPath - The DBus object path of the item

Throws:

AccessControlException

deleteItems

public void deleteItems(List<String> objectPaths) throws AccessControlException

Delete specified items from this collection.

Deleting passwords form the default collection requires user permission.

see: unlockWithUserPermission()

Specified by:

deleteItems in class SimpleCollection

Parameters:

objectPaths - The DBus object paths of the items

Throws:

AccessControlException

getTimeout

public Duration getTimeout()

Specified by:

getTimeout in class SimpleCollection

setTimeout

public void setTimeout(Duration timeout)

Specified by:

setTimeout in class SimpleCollection

isLocked

public boolean isLocked()

Specified by:

isLocked in class SimpleCollection