Simple Password Storage

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

## Synopsis

                        MateKeyringPasswordSchema;
    extern              const MateKeyringPasswordSchema* MATE_KEYRING_NETWORK_PASSWORD;
    #define             MATE_KEYRING_DEFAULT
    #define             MATE_KEYRING_SESSION
    gpointer            mate_keyring_store_password        (const MateKeyringPasswordSchema *schema,
                                                             const gchar *keyring,
                                                             const gchar *display_name,
                                                             const gchar *password,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data,
                                                             ...);
    MateKeyringResult  mate_keyring_store_password_sync   (const MateKeyringPasswordSchema *schema,
                                                             const gchar *keyring,
                                                             const gchar *display_name,
                                                             const gchar *password,
                                                             ...);
    gpointer            mate_keyring_find_password         (const MateKeyringPasswordSchema *schema,
                                                             MateKeyringOperationGetStringCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data,
                                                             ...);
    MateKeyringResult  mate_keyring_find_password_sync    (const MateKeyringPasswordSchema *schema,
                                                             gchar **password,
                                                             ...);
    gpointer            mate_keyring_delete_password       (const MateKeyringPasswordSchema *schema,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data,
                                                             ...);
    MateKeyringResult  mate_keyring_delete_password_sync  (const MateKeyringPasswordSchema *schema,
                                                             ...);
    void                mate_keyring_free_password         (gchar *password);

## Description

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 `MATE_KEYRING_NETWORK_PASSWORD`. Additional schemas can be defined via the `MateKeyringPasswordSchema` structure.

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 = mate_keyring_delete_password_sync (MATE_KEYRING_NETWORK_PASSWORD,
                                                "user", "me",        // A string attribute
                                                "server, "example.gnome.org",
                                                "port", "8080",      // An integer attribute
                                                NULL);

## Details

### MateKeyringPasswordSchema

    typedef struct {
    	MateKeyringItemType item_type;
    	struct {
    		const gchar* name;
    		MateKeyringAttributeType type;
    	} attributes[32];
    } MateKeyringPasswordSchema;

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

The last attribute name in a schema must be `NULL`.

      MateKeyringPasswordSchema my_schema = {
          MATE_KEYRING_ITEM_GENERIC_SECRET,
          {
               { "string-attr", MATE_KEYRING_ATTRIBUTE_TYPE_STRING },
               { "uint-attr", MATE_KEYRING_ATTRIBUTE_TYPE_UINT32 },
               { NULL, 0 }
          }
      };

MateKeyringItemType `item_type`; | The item type for this schema.

### MATE_KEYRING_NETWORK_PASSWORD

    extern const MateKeyringPasswordSchema* MATE_KEYRING_NETWORK_PASSWORD;

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.

### MATE_KEYRING_DEFAULT

    #define MATE_KEYRING_DEFAULT   NULL

The default keyring.

### MATE_KEYRING_SESSION

    #define MATE_KEYRING_SESSION   "session"

A keyring only stored in memory.

### mate_keyring_store_password ()

    gpointer            mate_keyring_store_password        (const MateKeyringPasswordSchema *schema,
                                                             const gchar *keyring,
                                                             const gchar *display_name,
                                                             const gchar *password,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data,
                                                             ...);

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 `mate_keyring_item_create()`.

`schema` : | The password schema.
`keyring` : | The keyring to store the password in. Specify `NULL` for the default keyring. Use `MATE_KEYRING_SESSION` to store the password in memory only.
`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`.
`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 asychronous request, which can be passed to `mate_keyring_cancel_request()`.

Since 2.22

### mate_keyring_store_password_sync ()

    MateKeyringResult  mate_keyring_store_password_sync   (const MateKeyringPasswordSchema *schema,
                                                             const gchar *keyring,
                                                             const gchar *display_name,
                                                             const gchar *password,
                                                             ...);

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 `mate_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 `mate_keyring_item_create_sync()`.

`schema` : | The password schema.
`keyring` : | The keyring to store the password in. Specify `NULL` for the default keyring. Use `MATE_KEYRING_SESSION` to store the password in memory only.
`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 : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

Since 2.22

### mate_keyring_find_password ()

    gpointer            mate_keyring_find_password         (const MateKeyringPasswordSchema *schema,
                                                             MateKeyringOperationGetStringCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data,
                                                             ...);

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 `mate_keyring_find_items()`.

`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`.
`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 asychronous request, which can be passed to `mate_keyring_cancel_request()`.

Since 2.22

### mate_keyring_find_password_sync ()

    MateKeyringResult  mate_keyring_find_password_sync    (const MateKeyringPasswordSchema *schema,
                                                             gchar **password,
                                                             ...);

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 `mate_keyring_find_password()`.

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

`schema` : | The password schema.
`password` : | An address to store password that was found. The password must be freed with `mate_keyring_free_password()`.
`...` : | 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 : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

Since 2.22

### mate_keyring_delete_password ()

    gpointer            mate_keyring_delete_password       (const MateKeyringPasswordSchema *schema,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data,
                                                             ...);

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 `mate_keyring_item_delete()`.

`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`.
`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 asychronous request, which can be passed to `mate_keyring_cancel_request()`.

Since 2.22

### mate_keyring_delete_password_sync ()

    MateKeyringResult  mate_keyring_delete_password_sync  (const MateKeyringPasswordSchema *schema,
                                                             ...);

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 `mate_keyring_delete_password()`.

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

`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 : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

Since 2.22

### mate_keyring_free_password ()

    void                mate_keyring_free_password         (gchar *password);

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.

`password` : | the password to be freed