[Authentication] Collection/Item unlocking

[Stef Walter]

Make sure to read 'On Compatibility and Features' mail posted to this
list to see my comments below in context.

Michael Leupold wrote:
> I was wondering if we really need individual-item unlocking? While on the 
> service side it's up to the implementor if he wants it, clients would have to 
> implement all of it to be able to communicate with every daemon.
> 
> So far I don't really see the benefit of it (an application could still create 
> while I clearly see how complicated things will get in my client code and 
> would prefer whole-collection unlocking only. Or is that meant to be able to 
> check acls on individual items?
> 
> Having collection-only locking we could introduce a "ChangeAuthentication" 
> call on collections which will initiate some GUI to change a collection's 
> authentication information (eg. a password to unlock) in the service.

Locking, ACLs, prompts are all the most challenging parts of this API.
I've seen a lot of it done wrong, or inflexibly, and want to make sure
we get it as close to 'right' as possible this time around.

The concept individual item unlocking is designed to make things easier
on applications. I agree that most implementations would encrypt and
prompt per collection.

First let's look at a daemon, and what it may choose to do:

 * Use fingerprint readers or non-password authentication.
 * Relock after a certain amount of uses.
 * Relock after a certain timeout.
 * One unlock for each application.
 * One unlock for all applications.
 * Prompt on each use.
 * ACLs.

Under the current system application's typical usage would be:

 * Search for items with Service.SearchCollections().
   Get back two sets some locked, and some unlocked.
 * If it wants to use the locked items it passes them to
   Session.BeginAuthenticate().
 * Either wait for Session.Authenticated signal or if user
   takes too long use Session.CompleteAuthenticate().
 * Use Service.RetrieveSecrets() to get the applications.

Obviously, a client side library may wrap the above.

When the service side gets a Session.BeginAuthenticate() for an item, it
 will often prompt for a password and unlock the entire collection.
Depending on the policy the user has chosen, this may be only unlocked
for a single client application or all apps, or any of a number of
possibilities.

Session.BeginAuthenticate() can also be used directly with collections
if it is locked. A password manager might do this to display an entire
collection.

If didn't have the concept of unlocking items directly things would be
more complex for applications:

 * Search for items with Service.SearchCollections().
 * Find the collection for each item.
 * Check each collection found to see which are locked.
 * Pass the list of locked collections (possibly one) to
   Session.BeginAuthenticate().
 * Either wait for Session.Authenticated signal or if user
   takes too long use Session.CompleteAuthenticate().
 * Use Service.RetrieveSecrets() to get the applications.

Remember that at any point a previously unlocked collection may become
locked again due to the implementation policy, or the user's requests.

> Having collection-only locking we could introduce a "ChangeAuthentication" 
> call on collections which will initiate some GUI to change a collection's 
> authentication information (eg. a password to unlock) in the service.

I feel that this must be implemented as an additional interface, which
password managers can use to control a collection.

Remember that service implementors may choose to implement locking
non-master-password methods such as:

 * Keys
 * Fingerprints
 * Prompts on a removable device.
 * Attaching a USB unlock stick.
 * Many other ideas....

While the above "ChangeAuthentication" suggestion does not exactly limit
a service implementor to use of master passwords, I still feel it's
better served as an additional interface, an implementation detail.

> Other questions related to unlocking as well:
> - org.freedesktop.Secrets.Collection.SearchItems - with individual-item 
> unlocking it should be specified if this searches ALL items or just unlocked 
> ones

All items, it finds unlocked ones. This is essential for a good user
experience. Otherwise the user will at times need to unlock a collection
in which there was nothing of interest.

Again, 'individual item unlocking' does not mean that items need to be
encrypted individually. Most service implementers will prompt for and
unlock an entire collection when an item in that collection is 'unlocked'.

> - org.freedesktop.Secrets.Service.SearchCollections - same as above. search 
> all or just unlocked? Furthermore, if results and locked are distinct I'd 
> rename "results" to "unlocked" to make it more clear.

Again all. Good point, about the changing the "results" argument.

> - org.freedesktop.Secrets.Service.RetrieveSecrets - The description should 
> specifiy that "secrets" returns items in the order queried for (so items[n] => 
> secrets[n]). There's currently no way this method can return an error if one 
> of the items is not found/locked. As it's nonetheless useful, it could return 
> secret structs with empty value so it would be up to the client to check if an 
> item exists.

Hmmm, that's true. But I wonder if there's a better way to do this. Null
values are not well represented in DBus. Should we instead return a dict
of object-path -> secret?

Again, none of the above is intended to be 'last word' even when I do
come across strongly :)

Cheers,

Stef