Chapter 8. Locking and Unlocking
Prev | Part I. API Documentation | Next

## Chapter 8. Locking and Unlocking

Some items and/or collections may be marked as locked by the service. The secrets of locked items cannot be accessed. Additionally, locked items or collections cannot be modified by the client application.

It's up to the service whether to unlock items individually, or collections as a whole. The client application should act as if it must unlock each item individually.

A service may upon unlocking a collection, unlock all items in that collection. If a service is not able to unlock an item individually, it should treat a request to unlock an item as a request to unlock the connection that the item is in.

A service may choose to unlock items or collections just for a single client application. Alternatively the service may choose to allow any client application to access items or collections unlocked by a another client application.

A client application should always be ready to unlock the items for the secrets it needs, or objects it must modify. It must not assume that an item is already unlocked for whatever reason.

A service may lock previously unlocked items for any reason at any time. Usually this is done in response to user actions, timeouts, or external actions (such as the computer sleeping). The inherent race conditions present due to this are unavoidable, and must be handled gracefully.

In order to unlock an item or collection the service's `Unlock()` method is called with one or more DBus object paths of items or collections. The `Unlock()` will return the DBus object paths of objects it could immediately unlock without prompting.

The `Unlock()` method may also return a prompt object. If a prompt object is returned, it must be acted upon in order to complete the unlocking of the remaining objects. The result of the prompt will contain the object paths that were successfully unlocked by the prompt.

In order to lock an item or collection the service's `Lock()` method is called with one or more DBus object paths of items or collections. The `Lock()` will return the DBus object paths of objects it could immediately lock without prompting.

The `Lock()` method may also return a prompt object. If a prompt object is returned, it must be acted upon in order to complete the locking of the remaining objects. The result of the prompt will contain the object paths that were successfully locked by the prompt.

Prev | Up | Next
Algorithm: dh-ietf1024-sha256-aes128-cbc-pkcs7 | Home | Chapter 9. Prompts and Prompting