The Secrets API allows client applications to store secrets securily in a service running in the user's login session.

The secrets are usually stored in an encrypted manner by the service. The service may need to be unlocked and/or authenticated by the user before the secrets become available for retrieval by client applications.

The Secrets service stores a secret along with a set of lookup attributes. The attributes can be used to lookup and retrieve a secret at a later date. The lookup attributes are not treated as secret material, and the service may choose to not encrypt attributes when storing them to disk.

A secret is something an application wishes to store securely. A good example is a password that an application needs to save and use at a later date.

Within this API a secret value is treated as an array of bytes. It is recommended that a secret consist of user readable text, although this API has no such requirement.

Applications wishing to store multiple values as part of a single secret, may choose to use a textual format to combine these values into one. For example, the 'desktop' key file format, or XML or another form of markup.

Secrets may be encrypted when transferred to the client application and vice versa.

The Secret structure encapsulates a secret value along with it's transfer encryption parameters.

Each secret is stored together with lookup attributes and a label. These together form an item.

A group of items together form a collection. A collection is similar in concept to the terms 'keyring' or 'wallet'.

Collections and items are represented as DBus objects, and each have their own object paths. However these may change from time to time.

It is strongly recommended that client applications use lookup attributes to find items rather than recording the object path of a stored item. This allows maximum interoperability.

An item or a collection may be initially in a locked state. When in a locked state the item or collection may not be modified in any way, and the secret may not be read. Client applications that require access to the secret of a locked item, or desire to modify a locked item, should unlock it before use.

The service must prevent locked collections or items from modification. On such an invalid access the IsLocked error should be raised.

Client applications without special requirements should store in the default collection. Use the DefaultCollection property on the Service interface to determine the default collection. In addition the default collection is always accessible through a specific object path.

Client applications with special needs can create a new collection by calling the CreateCollection() method on the Service interface. A client application must have opened a session before a collection can be created. The

A collection may be marked as private on creation. A private collection and the items within it may only be unlocked by the application that created the collection. Service implementors may choose not to implement this feature and should ignore the private argument when creating a collection. Client applications that demand this feature, should check the the Private property after creating a collection to see if the request for a private collection was ignored.

A collection can be deleted by calling the Delete() method on the Service interface. A client application must have opened a session before a collection can be created. However the collection does not need to be unlocked. In addition private collections can be deleted by any application.

Attributes can and should be stored with a secret to facilitate lookup of the secret at a later date.

An attribute constists of a name, and a value. Both parts are simple strings.

The service may have additional requirements as to what can be present in an attribute name. It is recommended that attribute names are human readable, and kept simple for the sake of simplicity.

During a lookup, attribute names and values are matched via case-sensitive string equality.

It's important to remember that attributes are not part of the secret. Services implementing this API will probably store attributes in an unencrypted manner in order to support simple and effecient lookups.

A session is established between a client application and a service. A session is used to unlock items and collections when necessary. It is also used to negotiate encryption of transferred secrets between the client application and the service.

A session is established by calling the service's OpenSession() method. Once established, a session is bound to calling application's connection to the DBus session bus. Generally only one session can be established per client application. Calling OpenSession() a second time results in an AlreadyExists error.

A session is closed when the client application disconnects from the DBus session bus. Alternatively the client application can call the Close() method on the session interface. Once a session is closed all session specific negotiations and authentication should be dropped by the service.

Since this is a D-Bus API, the data in all method calls and other accesses in this API will go through multiple processes, and may be cached arbitrarily by the OS or elsewhere.

The Secrets API has provision to encrypt secrets while in transit between the service and the client application.

The encryption is not envisioned to withstand man in the middle attacks, or other active attacks. It is envisioned to minimize storage of plain text secrets in memory and prevent storage plain text storage of secrets in a swap file or other caching mechanism.

Many client applications may choose not to make use of the provisions to encrypt secrets in transit. In fact for applications unable to prevent their own memory from being paged to disk (eg: Java, C# or Python apps), transfering encrypted secrets would be an excersize of questionable value.

This API was desigened by GNOME and KDE developers with the goal of having a common way to store secrets. It's predecessors are the desktop specific APIs used by GNOME Keyring and KWallet.

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

In order to unlock an item or collection a session is established by the client application, and the BeginAuthenticate() method is called with one or more DBus object paths of items or collections. The BeginAuthenticate() method is asynchronous and may return before the item is actually unlocked.

The service will then unlock the item or collection, perhaps by prompting the user for a password, or it could require use a hardware token of some sort.

After the service tries to unlock an item or collection, whether successfully or unsuccessfully, the Authenticated signal on the session interface is emitted.

The client application may, but is not required to, call the CompleteAuthenticate() method. One or more DBus object paths of items or collections that BeginAuthenticate() was previously called with, can be passed in. The CompleteAuthenticate() returns the items that were successfully authenticated. In addition if the unlock process is not yet complete for some items or collections, the service should stop trying to ask the user to unlock or authenticate them.

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. The Authenticated signal should however still be emitted for the individual items that were requested to be unlocked.

A service may choose to authenticate items or collections just for a single client application. Alternatively the service may choose to allow any client application to access items or collections authenticated by a single client application. A client application should always be ready to call BeginAuthenticate() 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 implement additional DBus interfaces for further capabilities not included in this specification. Password management applications or other narrowly focused tools should make use of these when necessary.

This specification does not mandate the use of master passwords to lock a collection of secrets. The service may choose to implement any method for authenticating secrets.

This specification does not mandate any form of access control. The service may choose to allow certain applications to access a keyring, and others.

[TODO: complete]

[TODO: complete]