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 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.

    • isGnomeKeyringAvailable

      public static boolean isGnomeKeyringAvailable()
      Checks if private/unsupported services are provided by the system:
      org.gnome.keyring
      Returns:
      true if the secret service provider is gnome keyring, otherwise false and will log a warning 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