The Secret Service API allows client applications to store secrets securely 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 by the user before the secrets become available for retrieval by client applications.

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

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

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, multiple values may be combined using the 'desktop' key file format, or XML.

Secrets may be encrypted when transferred to or from the client application.

The Secret structure encapsulates a secret value along with its 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 has its own object path. Under normal circumstances, the object path of a collection or item should not change for its lifetime.

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, must unlock it before use.

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

Client applications without special requirements should store in the default collection. The default collection is always accessible through a specific object path.

A new item can be created with the CreateItem() method on the Collection interface. When creating an item, the properties of the new item are specified. The service may ignore or change these properties when creating the item.

When creating an item, the service may need to prompt the user for additional information. In this case, a prompt object is returned. It must be acted upon in order for the collection to be created. In this case, the result of the prompt will contain the object path of the new item.

An item can be deleted by calling the Delete() method on the Item interface.

When deleting an item, the service may need to prompt the user for additional information. In this case, a prompt object is returned. It must be acted upon in order for the item to be deleted.

Client applications with special needs can create a new collection by calling the CreateCollection() method on the Service interface. When creating a collection, the properties of the new collection are specified. The service may ignore or change these properties when creating the collection.

When creating a collection, the service may need to prompt the user for additional information. In this case, a prompt object is returned. It must be acted upon in order for the collection to be created. In this case, the result of the prompt will contain the object path of the new collection.

A collection can be deleted by calling the Delete() method on the Collection interface.

When deleting a collection, the service may need to prompt the user for additional information. In this case, a prompt object is returned. It must be acted upon in order for the collection to be deleted.

Collections may be accessed via well known aliases. For example an alias called default tells applications which is the default collection to store secrets.

The aliased collections will be available at a well-known DBus object path.

If an application needs to create a collection with a given alias, this can be done in a race free fashion by specifying the alias parameter of the CreateCollection() method on the service interface. If a collection with that alias already exists, then it will be returned instead of creating a new one.

For applications like password managers it can be useful to allow the user to configure which collection is associated with which well known alias. To alias or unalias a collection use the SetAlias() method on the service interface. Use the ReadAlias() method on the service interface to discover which collection is associated with a given alias.

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.

In order to search for items, use the SearchItems() method of the Service interface. The matched items will be returned in two sets. The unlocked return value will contain the object paths of all the items that are not locked. The locked return value will contain object paths of items that are locked, which can be unlocked if desired.

The SearchItems() method of the Collection interface is similar, except for it only searches a single collection.

A session is established between a client application and a service. A session is used to transfer 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.

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 will be dropped by the service.

More than one session may opened by a client application, although this is not normally necessary.

To access or store secrets, use the GetSecret(), SetSecret() methods on the item interface, or the GetSecrets(), method on the service interface.

You must specify a session when retrieving or storing a secret. The session controls how the secret is encoded during transfer. 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 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), transferring encrypted secrets would be an exercise of questionable value.

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

In order to complete various operations, such as unlocking a collection, the service may need to prompt the user for additional information, such as a master password.

The prompts are displayed by the service on behalf of the client application.

Operations that require a prompt to complete will return a prompt object. The client application must then call the Prompt() method of the prompt object to display the prompt. Client applications can use the window-id argument to display the prompt attached to their application window.

Once the user provides the additional required information to the prompt, the service completes the operation that required the prompt. Then it emits the Completed signal of the prompt object. The result argument of the signal contains operation an operation specific result.

Either the user or the client application can dismiss a prompt. In this case the operation that required the additional information is cancelled. The client application can dismiss a prompt by calling the Dismiss() method of the prompt object. The Completed signal will be emitted with its dismissed argument set to TRUE.

Once the Completed signal is emitted on a prompt object, it is no longer valid. Prompt objects are specific to the client application's connection to the DBus bus. Once an application disconnects, all its prompts are no longer valid.

There is an inherent race between the Dismiss() method and the Completed signal. An application calling Dismiss() must be prepared to handle the fact that the Completed has already been emitted (although perhaps not received by the client). In addition the client must be prepared to handle the fact that the prompt object is no longer valid.

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 locking 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]

The various DBus object paths used with the Secret Service API are designed to be human readable but not displayed to the user. The object path of an item or collection should not change for its lifetime, under normal circumstances.

/org/freedesktop/secrets

The object path for the service.

/org/freedesktop/secrets/collection/xxxx

The object path for a collection, where xxxx represents a possibly encoded or truncated version of the initial label of the collection.

/org/freedesktop/secrets/collection/xxxx/iiii

The object path for an item, where xxxx is the collection (above) and iiii is an auto-generated item specific identifier.

/org/freedesktop/secrets/session/ssss

The object path for a session, where ssss is an auto-generated session specific identifier.

/org/freedesktop/secrets/aliases/default

The default collection for client applications to store secrets is available under this object path in addition to its real object path (above). Other aliases may also be present.

Errors returned by the Secret Service API.