Password storage

## Password storage Password storage — Simple password storage and lookup |

## Synopsis

    #include <secret/secret.h>

    #define             SECRET_COLLECTION_DEFAULT
    #define             SECRET_COLLECTION_SESSION
    void                secret_password_store               (const SecretSchema *schema,
                                                             const gchar *collection_path,
                                                             const gchar *label,
                                                             const gchar *password,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             ...);
    void                secret_password_storev              (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             const gchar *collection_path,
                                                             const gchar *label,
                                                             const gchar *password,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            secret_password_store_finish        (GAsyncResult *result,
                                                             GError **error);
    gboolean            secret_password_store_sync          (const SecretSchema *schema,
                                                             const gchar *collection_path,
                                                             const gchar *label,
                                                             const gchar *password,
                                                             GCancellable *cancellable,
                                                             GError **error,
                                                             ...);
    gboolean            secret_password_storev_sync         (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             const gchar *collection_path,
                                                             const gchar *label,
                                                             const gchar *password,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                secret_password_lookup              (const SecretSchema *schema,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             ...);
    void                secret_password_lookupv             (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gchar *             secret_password_lookup_finish       (GAsyncResult *result,
                                                             GError **error);
    gchar *             secret_password_lookup_nonpageable_finish
                                                            (GAsyncResult *result,
                                                             GError **error);
    gchar *             secret_password_lookup_sync         (const SecretSchema *schema,
                                                             GCancellable *cancellable,
                                                             GError **error,
                                                             ...);
    gchar *             secret_password_lookup_nonpageable_sync
                                                            (const SecretSchema *schema,
                                                             GCancellable *cancellable,
                                                             GError **error,
                                                             ...);
    gchar *             secret_password_lookupv_sync        (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gchar *             secret_password_lookupv_nonpageable_sync
                                                            (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                secret_password_remove              (const SecretSchema *schema,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             ...);
    void                secret_password_removev             (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            secret_password_remove_finish       (GAsyncResult *result,
                                                             GError **error);
    gboolean            secret_password_remove_sync         (const SecretSchema *schema,
                                                             GCancellable *cancellable,
                                                             GError **error,
                                                             ...);
    gboolean            secret_password_removev_sync        (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                secret_password_clear               (gchar *password);
    void                secret_password_free                (gchar *password);

## Description

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

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

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

Each of the functions accept a variable list of attributes names and their values. Include a `NULL` to terminate the list of attributes.

`stability`: Stable

## Details

### SECRET_COLLECTION_DEFAULT

    #define SECRET_COLLECTION_DEFAULT "/org/freedesktop/secrets/aliases/default"

### SECRET_COLLECTION_SESSION

    #define SECRET_COLLECTION_SESSION "/org/freedesktop/secrets/aliases/session"

### secret_password_store ()

    void                secret_password_store               (const SecretSchema *schema,
                                                             const gchar *collection_path,
                                                             const gchar *label,
                                                             const gchar *password,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             ...);

Store a password in the secret service.

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, an int number, or a gboolean value, as defined in the `schema`. The list of attribtues should be terminated with a `NULL`.

If the attributes match a secret item already stored in the collection, then the item will be updated with these new values.

If `collection_path` is `NULL`, then the default collection will be used. Use SECRET_COLLECTION_SESSION to store the password in the session collection, which doesn't get stored across login sessions.

This method will return immediately and complete asynchronously.

`schema` : | the schema for attributes
`collection_path` : | the D-Bus object path of the collection where to store the secret. [allow-none]
`label` : | label for the secret
`password` : | the null-terminated password to store
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to be passed to the callback
`...` : | the attribute keys and values, terminated with `NULL`

### secret_password_storev ()

    void                secret_password_storev              (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             const gchar *collection_path,
                                                             const gchar *label,
                                                             const gchar *password,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Store a password in the secret service.

The `attributes` should be a set of key and value string pairs.

If the attributes match a secret item already stored in the collection, then the item will be updated with these new values.

If `collection_path` is `NULL`, then the default collection will be used. Use SECRET_COLLECTION_SESSION to store the password in the session collection, which doesn't get stored across login sessions.

This method will return immediately and complete asynchronously.

Rename to: secret_password_store

`schema` : | the schema for attributes
`attributes` : | the attribute keys and values. [element-type utf8 utf8]
`collection_path` : | the D-Bus object path of the collection where to store the secret. [allow-none]
`label` : | label for the secret
`password` : | the null-terminated password to store
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to be passed to the callback

### secret_password_store_finish ()

    gboolean            secret_password_store_finish        (GAsyncResult *result,
                                                             GError **error);

### secret_password_store_sync ()

    gboolean            secret_password_store_sync          (const SecretSchema *schema,
                                                             const gchar *collection_path,
                                                             const gchar *label,
                                                             const gchar *password,
                                                             GCancellable *cancellable,
                                                             GError **error,
                                                             ...);

Store a password in the secret service.

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, an int number, or a gboolean value, as defined in the `schema`. The list of attribtues should be terminated with a `NULL`.

If the attributes match a secret item already stored in the collection, then the item will be updated with these new values.

If `collection_path` is `NULL`, then the default collection will be used. Use SECRET_COLLECTION_SESSION to store the password in the session collection, which doesn't get stored across login sessions.

This method may block indefinitely and should not be used in user interface threads.

`schema` : | the schema for attributes
`collection_path` : | the D-Bus object path of the collection where to store the secret. [allow-none]
`label` : | label for the secret
`password` : | the null-terminated password to store
`cancellable` : | optional cancellation object
`error` : | location to place an error on failure
`...` : | the attribute keys and values, terminated with `NULL`
Returns : | whether the storage was successful or not

### secret_password_storev_sync ()

    gboolean            secret_password_storev_sync         (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             const gchar *collection_path,
                                                             const gchar *label,
                                                             const gchar *password,
                                                             GCancellable *cancellable,
                                                             GError **error);

Store a password in the secret service.

The `attributes` should be a set of key and value string pairs.

If the attributes match a secret item already stored in the collection, then the item will be updated with these new values.

If `collection_path` is `NULL`, then the default collection will be used. Use SECRET_COLLECTION_SESSION to store the password in the session collection, which doesn't get stored across login sessions.

This method may block indefinitely and should not be used in user interface threads.

`schema` : | the schema for attributes
`attributes` : | the attribute keys and values. [element-type utf8 utf8]
`collection_path` : | the D-Bus object path of the collection where to store the secret. [allow-none]
`label` : | label for the secret
`password` : | the null-terminated password to store
`cancellable` : | optional cancellation object
`error` : | location to place an error on failure
Returns : | whether the storage was successful or not Rename to: secret_password_store_sync

### secret_password_lookup ()

    void                secret_password_lookup              (const SecretSchema *schema,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             ...);

Lookup a password in the secret service.

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, an int number, or a gboolean value, as defined in the password `schema`. The list of attribtues should be terminated with a `NULL`.

If no secret is found then `NULL` is returned.

This method will return immediately and complete asynchronously.

`schema` : | the schema for the attributes
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to be passed to the callback
`...` : | the attribute keys and values, terminated with `NULL`

### secret_password_lookupv ()

    void                secret_password_lookupv             (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Lookup a password in the secret service.

The `attributes` should be a set of key and value string pairs.

If no secret is found then `NULL` is returned.

This method will return immediately and complete asynchronously.

Rename to: secret_password_lookup

`schema` : | the schema for attributes
`attributes` : | the attribute keys and values. [element-type utf8 utf8]
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to be passed to the callback

### secret_password_lookup_finish ()

    gchar *             secret_password_lookup_finish       (GAsyncResult *result,
                                                             GError **error);

Finish an asynchronous operation to lookup a password in the secret service.

`result` : | the asynchronous result passed to the callback
`error` : | location to place an error on failure
Returns : | a new password string which should be freed with `secret_password_free()` or may be freed with `g_free()` when done. [transfer full]

### secret_password_lookup_nonpageable_finish ()

    gchar *             secret_password_lookup_nonpageable_finish
                                                            (GAsyncResult *result,
                                                             GError **error);

Finish an asynchronous operation to lookup a password in the secret service.

`result` : | the asynchronous result passed to the callback
`error` : | location to place an error on failure
Returns : | a new password string stored in nonpageable memory which must be freed with `secret_password_free()` when done. [transfer full]

### secret_password_lookup_sync ()

    gchar *             secret_password_lookup_sync         (const SecretSchema *schema,
                                                             GCancellable *cancellable,
                                                             GError **error,
                                                             ...);

Lookup a password in the secret service.

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, an int number, or a gboolean value, as defined in the password `schema`. The list of attribtues should be terminated with a `NULL`.

If no secret is found then `NULL` is returned.

This method may block indefinitely and should not be used in user interface threads.

`schema` : | the schema for the attributes
`cancellable` : | optional cancellation object
`error` : | location to place an error on failure
`...` : | the attribute keys and values, terminated with `NULL`
Returns : | a new password string which should be freed with `secret_password_free()` or may be freed with `g_free()` when done. [transfer full]

### secret_password_lookup_nonpageable_sync ()

    gchar *             secret_password_lookup_nonpageable_sync
                                                            (const SecretSchema *schema,
                                                             GCancellable *cancellable,
                                                             GError **error,
                                                             ...);

Lookup a password in the secret service.

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, an int number, or a gboolean value, as defined in the password `schema`. The list of attribtues should be terminated with a `NULL`.

If no secret is found then `NULL` is returned.

This method may block indefinitely and should not be used in user interface threads.

`schema` : | the schema for the attributes
`cancellable` : | optional cancellation object
`error` : | location to place an error on failure
`...` : | the attribute keys and values, terminated with `NULL`
Returns : | a new password string stored in nonpageable memory which must be freed with `secret_password_free()` when done. [transfer full]

### secret_password_lookupv_sync ()

    gchar *             secret_password_lookupv_sync        (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GError **error);

Lookup a password in the secret service.

The `attributes` should be a set of key and value string pairs.

If no secret is found then `NULL` is returned.

This method may block indefinitely and should not be used in user interface threads.

`schema` : | the schema for attributes
`attributes` : | the attribute keys and values. [element-type utf8 utf8]
`cancellable` : | optional cancellation object
`error` : | location to place an error on failure
Returns : | a new password string which should be freed with `secret_password_free()` or may be freed with `g_free()` when done Rename to: secret_password_lookup_sync. [transfer full]

### secret_password_lookupv_nonpageable_sync ()

    gchar *             secret_password_lookupv_nonpageable_sync
                                                            (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GError **error);

Lookup a password in the secret service.

The `attributes` should be a set of key and value string pairs.

If no secret is found then `NULL` is returned.

This method may block indefinitely and should not be used in user interface threads.

`schema` : | the schema for attributes
`attributes` : | the attribute keys and values. [element-type utf8 utf8]
`cancellable` : | optional cancellation object
`error` : | location to place an error on failure
Returns : | a new password string stored in non pageable memory which should be freed with `secret_password_free()` when done. [transfer full]

### secret_password_remove ()

    void                secret_password_remove              (const SecretSchema *schema,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             ...);

Remove a password from the secret service.

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, an int number, or a gboolean value, as defined in the password `schema`. The list of attribtues should be terminated with a `NULL`.

If multiple items match the attributes, then only one will be deleted.

This method will return immediately and complete asynchronously.

`schema` : | the schema for the attributes
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to be passed to the callback
`...` : | the attribute keys and values, terminated with `NULL`

### secret_password_removev ()

    void                secret_password_removev             (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Remove a password from the secret service.

The `attributes` should be a set of key and value string pairs.

If multiple items match the attributes, then only one will be deleted.

This method will return immediately and complete asynchronously.

Rename to: secret_password_remove

`schema` : | the schema for the attributes
`attributes` : | the attribute keys and values. [element-type utf8 utf8]
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to be passed to the callback

### secret_password_remove_finish ()

    gboolean            secret_password_remove_finish       (GAsyncResult *result,
                                                             GError **error);

Finish an asynchronous operation to remove a password from the secret service.

`result` : | the asynchronous result passed to the callback
`error` : | location to place an error on failure
Returns : | whether the removal was successful or not

### secret_password_remove_sync ()

    gboolean            secret_password_remove_sync         (const SecretSchema *schema,
                                                             GCancellable *cancellable,
                                                             GError **error,
                                                             ...);

Remove a password from the secret service.

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, an int number, or a gboolean value, as defined in the password `schema`. The list of attribtues should be terminated with a `NULL`.

If multiple items match the attributes, then only one will be deleted.

This method may block indefinitely and should not be used in user interface threads.

`schema` : | the schema for the attributes
`cancellable` : | optional cancellation object
`error` : | location to place an error on failure
`...` : | the attribute keys and values, terminated with `NULL`
Returns : | whether the removal was successful or not

### secret_password_removev_sync ()

    gboolean            secret_password_removev_sync        (const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GError **error);

Remove a password from the secret service.

The `attributes` should be a set of key and value string pairs.

If multiple items match the attributes, then only one will be deleted.

This method may block indefinitely and should not be used in user interface threads.

`schema` : | the schema for the attributes
`attributes` : | the attribute keys and values. [element-type utf8 utf8]
`cancellable` : | optional cancellation object
`error` : | location to place an error on failure
Returns : | whether the removal was successful or not Rename to: secret_password_remove_sync

### secret_password_clear ()

    void                secret_password_clear               (gchar *password);

Clear the memory used by a password.

`password` : | password to clear. [allow-none]

### secret_password_free ()

    void                secret_password_free                (gchar *password);

Clear the memory used by a password, and then free it.

This function must be used to free nonpageable memory returned by `secret_password_lookup_nonpageable_finish()`, `secret_password_lookup_nonpageable_sync()` or `secret_password_lookupv_nonpageable_sync()`.

`password` : | password to free. [allow-none]