Simple Password Storage: gnome-keyring Reference Manual

Simple Password Storage

Simple Password Storage — Store and lookup passwords with a set of attributes.

Functions

gpointer	gnome_keyring_store_password ()
GnomeKeyringResult	gnome_keyring_store_password_sync ()
gpointer	gnome_keyring_find_password ()
GnomeKeyringResult	gnome_keyring_find_password_sync ()
gpointer	gnome_keyring_delete_password ()
GnomeKeyringResult	gnome_keyring_delete_password_sync ()
void	gnome_keyring_free_password ()

Types and Values

	GnomeKeyringPasswordSchema
	GnomeKeyringPasswordSchemaAttribute
extern const GnomeKeyringPasswordSchema*	GNOME_KEYRING_NETWORK_PASSWORD
#define	GNOME_KEYRING_DEFAULT
#define	GNOME_KEYRING_SESSION

Description

All of these APIs are deprecated. Use libsecret instead.

This is a simple API for storing passwords and retrieving passwords in the keyring.

Each password is associated with a set of attributes. Attribute values can be either strings or unsigned integers.

The names and types of allowed attributes for a given password are defined with a schema. Certain schemas are predefined such as GNOME_KEYRING_NETWORK_PASSWORD. Additional schemas can be defined via the GnomeKeyringPasswordSchema structure.

Attributes are not stored in a secret or encrypted manner by gnome-keyring. Do not store sensitive information in attributes.

Each function accepts a variable list of attributes names and their values. Include a NULL to terminate the list of attributes.

Example 1. Passing attributes to the functions

res = gnome_keyring_delete_password_sync (GNOME_KEYRING_NETWORK_PASSWORD,
                                          "user", "me",        // A string attribute
                                          "server, "example.gnome.org",
                                          "port", "8080",      // An integer attribute
                                          NULL);

Functions

gnome_keyring_store_password ()

gpointer
gnome_keyring_store_password (const GnomeKeyringPasswordSchema *schema,
                              const gchar *keyring,
                              const gchar *display_name,
                              const gchar *password,
                              GnomeKeyringOperationDoneCallback callback,
                              gpointer data,
                              GDestroyNotify destroy_data,
                              ...);

gnome_keyring_store_password is deprecated and should not be used in newly-written code.

Use secret_password_store() instead.

Store a password associated with a given set of attributes.

Attributes which identify this password must be passed as additional arguments. Attributes passed must be defined in the schema.

If a password exists in the keyring that already has all the same arguments, then the password will be updated.

Another more complex way to create a keyring item is using gnome_keyring_item_create().

[skip]

Parameters

schema	The password schema.
keyring	The keyring to store the password in. Specify `NULL` for the default keyring. Use `GNOME_KEYRING_SESSION` to store the password in memory only.	[allow-none]
display_name	A human readable description of what the password is for.
password	The password to store.
callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.
...	The variable argument list should contain pairs of a) The attribute name as a null terminated string, followed by b) attribute value, either a character string, or 32-bit unsigned int, as defined in the password `schema` . The list of attribtues should be terminated with a `NULL`.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

Since: 2.22

gnome_keyring_store_password_sync ()

GnomeKeyringResult
gnome_keyring_store_password_sync (const GnomeKeyringPasswordSchema *schema,
                                   const gchar *keyring,
                                   const gchar *display_name,
                                   const gchar *password,
                                   ...);

gnome_keyring_store_password_sync is deprecated and should not be used in newly-written code.

Use secret_password_store_sync() instead.

Store a password associated with a given set of attributes.

Attributes which identify this password must be passed as additional arguments. Attributes passed must be defined in the schema.

This function may block for an unspecified period. If your application must remain responsive to the user, then use gnome_keyring_store_password().

If a password exists in the keyring that already has all the same arguments, then the password will be updated.

Another more complex way to create a keyring item is using gnome_keyring_item_create_sync().

[skip]

Parameters

schema	The password schema.
keyring	The keyring to store the password in. Specify `NULL` for the default keyring. Use `GNOME_KEYRING_SESSION` to store the password in memory only.	[allow-none]
display_name	A human readable description of what the password is for.
password	The password to store.
...	The variable argument list should contain pairs of a) The attribute name as a null terminated string, followed by b) attribute value, either a character string, or 32-bit unsigned int, as defined in the password `schema` . The list of attribtues should be terminated with a `NULL`.

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

Since: 2.22

gnome_keyring_find_password ()

gpointer
gnome_keyring_find_password (const GnomeKeyringPasswordSchema *schema,
                             GnomeKeyringOperationGetStringCallback callback,
                             gpointer data,
                             GDestroyNotify destroy_data,
                             ...);

gnome_keyring_find_password is deprecated and should not be used in newly-written code.

Use secret_password_lookup() instead.

Find a password that matches a given set of attributes.

Attributes which identify this password must be passed as additional arguments. Attributes passed must be defined in the schema.

The string that is passed to callback is automatically freed when the function returns.

Another more complex way to find items in the keyrings is using gnome_keyring_find_items().

[skip]

Parameters

schema	The password schema.
callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.
...	The variable argument list should contain pairs of a) The attribute name as a null terminated string, followed by b) attribute value, either a character string, or 32-bit unsigned int, as defined in the password `schema` . The list of attribtues should be terminated with a `NULL`.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

Since: 2.22

gnome_keyring_find_password_sync ()

GnomeKeyringResult
gnome_keyring_find_password_sync (const GnomeKeyringPasswordSchema *schema,
                                  gchar **password,
                                  ...);

gnome_keyring_find_password_sync is deprecated and should not be used in newly-written code.

Use secret_password_lookup_sync() instead.

Find a password that matches a given set of attributes.

Attributes which identify this password must be passed as additional arguments. Attributes passed must be defined in the schema.

This function may block for an unspecified period. If your application must remain responsive to the user, then use gnome_keyring_find_password().

Another more complex way to find items in the keyrings is using gnome_keyring_find_items_sync().

[skip]

Parameters

schema	The password schema.
password	An address to store password that was found. The password must be freed with `gnome_keyring_free_password()`.	[out]
...	The variable argument list should contain pairs of a) The attribute name as a null terminated string, followed by b) attribute value, either a character string, or 32-bit unsigned int, as defined in the password `schema` . The list of attribtues should be terminated with a `NULL`.

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

Since: 2.22

gnome_keyring_delete_password ()

gpointer
gnome_keyring_delete_password (const GnomeKeyringPasswordSchema *schema,
                               GnomeKeyringOperationDoneCallback callback,
                               gpointer data,
                               GDestroyNotify destroy_data,
                               ...);

gnome_keyring_delete_password is deprecated and should not be used in newly-written code.

Use secret_password_clear() instead.

Delete a password that matches a given set of attributes.

Attributes which identify this password must be passed as additional arguments. Attributes passed must be defined in the schema.

Another more complex way to find items in the keyrings is using gnome_keyring_item_delete().

[skip]

Parameters

schema	The password schema.
callback	A callback which will be called when the request completes or fails.
data	A pointer to arbitrary data that will be passed to the `callback` .	[allow-none]
destroy_data	A function to free `data` when it's no longer needed.
...	The variable argument list should contain pairs of a) The attribute name as a null terminated string, followed by b) attribute value, either a character string, or 32-bit unsigned int, as defined in the password `schema` . The list of attribtues should be terminated with a `NULL`.

Returns

The asynchronous request, which can be passed to gnome_keyring_cancel_request().

[transfer none]

Since: 2.22

gnome_keyring_delete_password_sync ()

GnomeKeyringResult
gnome_keyring_delete_password_sync (const GnomeKeyringPasswordSchema *schema,
                                    ...);

gnome_keyring_delete_password_sync is deprecated and should not be used in newly-written code.

Use secret_password_clear_sync() instead.

Delete a password that matches a given set of attributes.

Attributes which identify this password must be passed as additional arguments. Attributes passed must be defined in the schema.

This function may block for an unspecified period. If your application must remain responsive to the user, then use gnome_keyring_delete_password().

Another more complex way to find items in the keyrings is using gnome_keyring_item_delete_sync().

[skip]

Parameters

schema	The password schema.
...	The variable argument list should contain pairs of a) The attribute name as a null terminated string, followed by b) attribute value, either a character string, or 32-bit unsigned int, as defined in the password `schema` . The list of attribtues should be terminated with a `NULL`.

Returns

GNOME_KEYRING_RESULT_OK if the operation was succcessful or an error result otherwise.

Since: 2.22

gnome_keyring_free_password ()

void
gnome_keyring_free_password (gchar *password);

gnome_keyring_free_password is deprecated and should not be used in newly-written code.

Use secret_password_free() instead.

Clears the memory used by password by filling with '\0' and frees the memory after doing this. You should use this function instead of g_free() for secret information.

Parameters

password

the password to be freed

Types and Values

GnomeKeyringPasswordSchema

typedef struct {
	GnomeKeyringItemType item_type;
	struct {
		const gchar* name;
		GnomeKeyringAttributeType type;
	} attributes[32];
} GnomeKeyringPasswordSchema;

GnomeKeyringPasswordSchema is deprecated and should not be used in newly-written code.

Describes a password schema. Often you'll want to use a predefined schema such as GNOME_KEYRING_NETWORK_PASSWORD.

The last attribute name in a schema must be NULL.

  GnomeKeyringPasswordSchema my_schema = {
      GNOME_KEYRING_ITEM_GENERIC_SECRET,
      {
           { "string-attr", GNOME_KEYRING_ATTRIBUTE_TYPE_STRING },
           { "uint-attr", GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32 },
           { NULL, 0 }
      }
  };

Members

GnomeKeyringItemType item_type;

The item type for this schema.

GnomeKeyringPasswordSchemaAttribute

typedef struct {
	const gchar* name;
	GnomeKeyringAttributeType type;
} GnomeKeyringPasswordSchemaAttribute;

GnomeKeyringPasswordSchemaAttribute is deprecated and should not be used in newly-written code.

One attribute of a GnomeKeyringPasswordSchema.

Members

const gchar *`name`;	the attribute name
GnomeKeyringAttributeType `type`;	the attribute data type

GNOME_KEYRING_NETWORK_PASSWORD

extern const GnomeKeyringPasswordSchema* GNOME_KEYRING_NETWORK_PASSWORD;

GNOME_KEYRING_NETWORK_PASSWORD is deprecated and should not be used in newly-written code.

A predefined schema for network paswsords. It contains the following attributes:

user: A string for the user login.
server: The server being connected to.
protocol: The protocol used to access the server, such as 'http' or 'smb'
domain: A realm or domain, such as a Windows login domain.
port: The network port to used to connect to the server.

GNOME_KEYRING_DEFAULT

#define GNOME_KEYRING_DEFAULT   NULL

GNOME_KEYRING_DEFAULT is deprecated and should not be used in newly-written code.

The default keyring.

GNOME_KEYRING_SESSION

#define GNOME_KEYRING_SESSION   "session"

GNOME_KEYRING_SESSION is deprecated and should not be used in newly-written code.

A keyring only stored in memory.