diff options
author | Stefan Walter <stefw@src.gnome.org> | 2007-03-31 17:45:10 +0000 |
---|---|---|
committer | Stefan Walter <stefw@src.gnome.org> | 2007-03-31 17:45:10 +0000 |
commit | aaa44524aea464ba3aa70f9f118a273c02e1db2b (patch) | |
tree | d2a4f936ce3ee8632a5b98bf1f51dc9ced46db07 /keyring-intro.txt | |
parent | c8904a8578212bda92aa051fea2dcef2168eb2de (diff) | |
download | gnome-keyring-aaa44524aea464ba3aa70f9f118a273c02e1db2b.tar.gz |
Reorganized file tree. All library and common files All daemon files
* Reorganized file tree.
* library/*: All library and common files
* daemon/*: All daemon files
* doc/*: Random documentation
* configure.in: Updated version number development version
svn path=/trunk/; revision=569
Diffstat (limited to 'keyring-intro.txt')
-rw-r--r-- | keyring-intro.txt | 152 |
1 files changed, 0 insertions, 152 deletions
diff --git a/keyring-intro.txt b/keyring-intro.txt deleted file mode 100644 index 4d788c1f..00000000 --- a/keyring-intro.txt +++ /dev/null @@ -1,152 +0,0 @@ -GNOME Keyring is a system to store passwords and other sensitive data in a -standardized way across all GNOME applications. - -A keyring stores a collection of encrypted passwords and encrypted information -about those passwords. A user can have multiple keyrings, each for a different -use, but there is a "default" one. There is also a special "session" keyring -which is not stored on disk and goes away when you log out. - -When a user logs into GNOME, the keyrings are locked and a master keyring -password has to be provided in order to unlock each of them. A keyring can be -configured to be locked automatically after a period of inactivity (This isn't -actually implemented yet but is coming soon) - -The data inside a keyring is stored in "items". An item can be of these types: - - GNOME_KEYRING_ITEM_GENERIC_SECRET - GNOME_KEYRING_ITEM_NETWORK_PASSWORD - GNOME_KEYRING_ITEM_NOTE - -Notice that we might extend the set of types as necessary. - -Each item has a name, such as "university proxy password" or "example.org SSH -private key password", a secret, and an unlimited list of attributes. Each -attribute consists of a name-value pair that is intended to serve as a hint for -the applications (e.g., "user=fer", or "server=example.org"). This enables -applications to find the relevant item in the keyring. All strings are UTF-8. -Attributes can be integers or strings. - - -Storing a password in a keyring -------------------------------- - -Applications should provide the user an opportunity to select the keyring in -which to store the password. The default keyring can be obtained by calling - - gnome_keyring_get_default_keyring - -while a list of all available keyrings can be obtained by calling the - - gnome_keyring_list_keyring_names - -function. Passing NULL for keyring parameter in any gnome-keyring function -will use the default one. - -The example code below demonstrates how to add the new password (and associated -data) into the selected keyring: - - - GnomeKeyringAttributeList *attributes; - GnomeKeyringAttribute attribute; - - attributes = gnome_keyring_attribute_list_new (); - - attribute.name = g_strdup ("user"); - attribute.type = GNOME_KEYRING_ATTRIBUTE_TYPE_STRING; - attribute.value.string = g_strdup ("gnomer"); - g_array_append_val (attributes, attribute); - - attribute.name = g_strdup ("server"); - attribute.type = GNOME_KEYRING_ATTRIBUTE_TYPE_STRING; - attribute.value.string = g_strdup ("master.gnome.org"); - g_array_append_val (attributes, attribute); - - attribute.name = g_strdup ("protocol"); - attribute.type = GNOME_KEYRING_ATTRIBUTE_TYPE_STRING; - attribute.value.string = g_strdup ("ssh"); - g_array_append_val (attributes, attribute); - - gnome_keyring_item_create (NULL, /* Use default keyring */ - GNOME_KEYRING_ITEM_NETWORK_PASSWORD, /* type */ - "master.gnome.org SSH password", /* name */ - attributes, /* attribute list */ - "mypassword", /* password */ - TRUE, /* Update if already exists */ - create_item_cb, NULL, NULL); - gnome_keyring_attribute_list_free (attributes); - - -In most cases, applications must use standard attributes. There is a convenience -function in gnome-keyring to aid in setting these attributes: - - gnome_keyring_set_network_password (NULL /* default keyring */, - "gnomer" /* user */ - NULL, /* domain */ - "master.gnome.org", /* server */ - NULL, /* object */ - "ssh", /* protocol */ - NULL, /* authtype */ - 0, /* port, default */ - "mypassword", /* password */ - set_network_cb, NULL, NULL); - - -Retrieving a password in a keyring ----------------------------------- - -Typically, applications will search for a password that matches certain -criteria. This is done by providing a list of specific attributes to the - - gnome_keyring_find_items - -function. In the common case that an application is searching for a network -password, however, there is a convenience function that can be used instead: - - - gnome_keyring_find_network_password_sync ("gnomer", /* user */ - NULL, /* domain */ - "master.gnome.org", /* server */ - NULL, /* object */ - "ssh", /* protocol */ - NULL, /* authtype */ - 0, /* port */ - &list); - - -In this example, list is a GList containing GnomeKeyringNetworkPasswordData -entries. - -The search is performed by the GNOME Keyring daemon, which looks through the -passwords on every keyring. The daemon gathers a list of all of the items -(passwords) that match the specified criteria. The returned list can contain -several matches, for instance {server=foo, user=bar} and {server=foo}. The -daemon always orders these such that the ones that match the least of the -query are returned first. - -This is so that you can for instance have two passwords on the same -machine, but say on different ports, and one is the default port (not -set). Then just querying for the server will give you the one without -the additional port. - -For each item, it then asks the user whether to allow the application that -requested the item to receive it. Only the items allowed by the user are -given to the application. - -Note that multiple ways of approving key usage are provided to the user, such -as "Deny", "Allow this time", "Allow always". - - -Some notes about gnome-keyring API ----------------------------------- - -Most GNOME Keyring functions are asynchronous. Because of this, callback -functions should be provided that will be executed when the required operation -has finished. For those that prefer synchronous operation, there are -synchronous variants of common gnome-keyring functions: - - gnome_keyring_find_items_sync - gnome_keyring_find_itemsv_sync - gnome_keyring_item_create_sync - gnome_keyring_find_network_password_sync - gnome_keyring_set_network_password_sync - |