secret.c.types

Flags which determine which parts of the #SecretBackend are initialized.

Flags for [secret.collection.Collection.create].

Flags which determine which parts of the #SecretCollection proxy are initialized.

Errors returned by the Secret Service.

None of the errors are appropriate for display to the user. It is up to the application to handle them appropriately.

Flags for [secret.item.Item.create].

Flags which determine which parts of the #SecretItem proxy are initialized.

The type of an attribute in a struct@SecretSchema.

Attributes are stored as strings in the Secret Service, and the attribute types simply define standard ways to store integer and boolean values as strings.

Flags for a #SecretSchema definition.

Different types of schemas for storing secrets, intended for use with func@get_schema.

@SECRET_SCHEMA_NOTE

A predefined schema for personal passwords stored by the user in the password manager. This schema has no attributes, and the items are not meant to be used automatically by applications.

When used to search for items using this schema, it will only match items that have the same schema. Items stored via libgnome-keyring with the GNOME_KEYRING_ITEM_NOTE item type will match.

@SECRET_SCHEMA_COMPAT_NETWORK

A predefined schema that is compatible with items stored via the libgnome-keyring 'network password' functions. This is meant to be used by applications migrating from libgnome-keyring which stored their secrets as 'network passwords'. It is not recommended that new code use this schema.

When used to search for items using this schema, it will only match items that have the same schema. Items stored via libgnome-keyring with the GNOME_KEYRING_ITEM_NETWORK_PASSWORD item type will match.

The following attributes exist in the schema:

Attributes:

Various flags to be used with [secret.service.Service.search] and [secret.service.Service.searchSync].

Flags which determine which parts of the #SecretService proxy are initialized during a [secret.service.Service.get] or [secret.service.Service.open] operation.

#SecretBackend represents a backend implementation of password storage.

The interface for #SecretBackend.

A proxy object representing a collection of secrets in the Secret Service.

#SecretCollection represents a collection of secret items stored in the Secret Service.

A collection can be in a locked or unlocked state. Use method@SecretService.lock or method@SecretService.unlock to lock or unlock the collection.

Use the property@SecretCollection:items property or method@SecretCollection.get_items to lookup the items in the collection. There may not be any items exposed when the collection is locked.

The class for #SecretCollection.

A secret item

#SecretItem represents a secret item stored in the Secret Service.

Each item has a value, represented by a struct@Value, which can be retrieved by [secret.item.Item.getSecret] or set by [secret.item.Item.setSecret]. The item is only available when the item is not locked.

Items can be locked or unlocked using the [secret.service.Service.lock] or [secret.service.Service.unlock] functions. The Secret Service may not be able to unlock individual items, and may unlock an entire collection when a single item is unlocked.

Each item has a set of attributes, which are used to locate the item later. These are not stored or transferred in a secure manner. Each attribute has a string name and a string value. Use [secret.service.Service.search] to search for items based on their attributes, and [secret.item.Item.setAttributes] to change the attributes associated with an item.

Items can be created with [secret.item.Item.create] or [secret.service.Service.store].

The class for #SecretItem.

A prompt in the Service

A proxy object representing a prompt that the Secret Service will display to the user.

Certain actions on the Secret Service require user prompting to complete, such as creating a collection, or unlocking a collection. When such a prompt is necessary, then a #SecretPrompt object is created by this library, and passed to the [secret.service.Service.prompt] method. In this way it is handled automatically.

In order to customize prompt handling, override the vfunc@Service.prompt_async and vfunc@Service.prompt_finish virtual methods of the class@Service class.

The class for #SecretPrompt.

A read-only view of a secret item in the Secret Service.

#SecretRetrievable provides a read-only view of a secret item stored in the Secret Service.

Each item has a value, represented by a struct@Value, which can be retrieved by [secret.retrievable.Retrievable.retrieveSecret] and [secret.retrievable.Retrievable.retrieveSecretFinish].

The interface for #SecretRetrievable.

Represents a set of attributes that are stored with an item.

These schemas are used for interoperability between various services storing the same types of items.

Each schema has a name like org.gnome.keyring.NetworkPassword, and defines a set of attributes, and types (string, integer, boolean) for those attributes.

Attributes are stored as strings in the Secret Service, and the attribute types simply define standard ways to store integer and boolean values as strings. Attributes are represented in libsecret via a [glib.hash_table.HashTable] with string keys and values. Even for values that defined as an integer or boolean in the schema, the attribute values in the [glib.hash_table.HashTable] are strings. Boolean values are stored as the strings 'true' and 'false'. Integer values are stored in decimal, with a preceding negative sign for negative integers.

Schemas are handled entirely on the client side by this library. The name of the schema is automatically stored as an attribute on the item.

Normally when looking up passwords only those with matching schema names are returned. If the schema @flags contain the [secret.types.SchemaFlags.DontMatchName] flag, then lookups will not check that the schema name matches that on the item, only the schema's attributes are matched. This is useful when you are looking up items that are not stored by the libsecret library. Other libraries such as libgnome-keyring don't store the schema name.

Additional schemas can be defined via the struct@Schema structure like this:

// in a header:

const SecretSchema * example_get_schema (void) G_GNUC_CONST;

#define EXAMPLE_SCHEMA  example_get_schema ()

// in a .c file

const SecretSchema *
example_get_schema (void)
{
   static const SecretSchema the_schema = {
       "org.example.Password", SECRET_SCHEMA_NONE,
       {
           {  "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
           {  "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
           {  "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
           {  NULL, 0 },
       }
   };
   return &the_schema;
}

An attribute in a #SecretSchema.

A proxy object representing the Secret Service.

A #SecretService object represents the Secret Service implementation which runs as a D-Bus service.

Normally a single #SecretService object can be shared between multiple callers. The [secret.service.Service.get] method is used to access this #SecretService object. If a new independent #SecretService object is required, use [secret.service.Service.open].

In order to securely transfer secrets to the Sercret Service, a session is established. This session can be established while initializing a #SecretService object by passing the [secret.types.ServiceFlags.OpenSession] flag to the [secret.service.Service.get] or [secret.service.Service.open] functions. In order to establish a session on an already existing #SecretService, use the [secret.service.Service.ensureSession] function.

To search for items, use the [secret.service.Service.search] method.

Multiple collections can exist in the Secret Service, each of which contains secret items. In order to instantiate class@Collection objects which represent those collections while initializing a #SecretService then pass the [secret.types.ServiceFlags.LoadCollections] flag to the [secret.service.Service.get] or [secret.service.Service.open] functions. In order to establish a session on an already existing #SecretService, use the [secret.service.Service.loadCollections] function. To access the list of collections use [secret.service.Service.getCollections].

Certain actions on the Secret Service require user prompting to complete, such as creating a collection, or unlocking a collection. When such a prompt is necessary, then a class@Prompt object is created by this library, and passed to the [secret.service.Service.prompt] method. In this way it is handled automatically.

In order to customize prompt handling, override the vfunc@Service.prompt_async and vfunc@Service.prompt_finish virtual methods of the #SecretService class.

The class for #SecretService.

A value containing a secret

A #SecretValue contains a password or other secret value.

Use [secret.value.Value.get] to get the actual secret data, such as a password. The secret data is not necessarily null-terminated, unless the content type is "text/plain".

Each #SecretValue has a content type. For passwords, this is text/plain. Use [secret.value.Value.getContentType] to look at the content type.

#SecretValue is reference counted and immutable. The secret data is only freed when all references have been released via [secret.value.Value.unref].