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.
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 `org.freedesktop.secrets` is provided as D-Bus service.
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 D-Bus. 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 D-Bus. Check the logs.

Method Details

isAvailable

public static boolean isAvailable()

Checks if `org.freedesktop.secrets` is provided as D-Bus service.

Returns:

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

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

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

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

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

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

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

isLocked

public boolean isLocked()

Specified by:

isLocked in class SimpleCollection

setTimeout

public void setTimeout(Duration timeout)

Specified by:

setTimeout in class SimpleCollection