TrackerPasswordProvider

TrackerPasswordProvider — Password storage interface for cross platform backends

Functions

Types and Values

Object Hierarchy


Includes

#include <libtracker-miner/tracker-miner.h>

Description

The TrackerPasswordProvider allows different backends to be written for storing sensitive information about web services which are needed to authenticate and mine data. Currently, there are two implementations. One for GNOME Keyring and one using GKeyFile (as a fallback if GNOME Keyring is installed).

Functions

tracker_password_provider_error_quark ()

GQuark
tracker_password_provider_error_quark (void);

Returns

the GQuark used to identify password provider errors in GError structures.

Since 0.8


tracker_password_provider_forget_password ()

void
tracker_password_provider_forget_password
                               (TrackerPasswordProvider *provider,
                                const gchar *service,
                                GError **error);

This function calls the password provider's "forget_password" implementation with service .

On failure error will be set.

Parameters

provider

a TrackerPasswordProvider

 

service

the name of the remote service associated with username

 

error

return location for errors.

[out callee-allocates][transfer full][allow-none]

Since 0.8


tracker_password_provider_get ()

TrackerPasswordProvider *
tracker_password_provider_get (void);

This function MUST be defined by the implementation of TrackerPasswordProvider.

For example, tracker-password-provider-gnome.c should include this function for a GNOME Keyring implementation.

Only one implementation can exist at once.

Since 0.8


tracker_password_provider_get_name ()

gchar *
tracker_password_provider_get_name (TrackerPasswordProvider *provider);

At the moment there are only two providers, "GNOME Keyring" and "GKeyFile". Either of these is what will be returned unless new providers are written.

Parameters

provider

a TrackerPasswordProvider

 

Returns

a newly allocated string representing the name which must be freed with g_free().

[out][transfer full]

Since 0.8


tracker_password_provider_get_password ()

gchar *
tracker_password_provider_get_password
                               (TrackerPasswordProvider *provider,
                                const gchar *service,
                                gchar **username,
                                GError **error);

This function calls the password provider's "get_password" implementation with service and username .

Parameters

provider

a TrackerPasswordProvider

 

service

the name of the remote service associated with username

 

username

the username associated with the password we are returning.

[out]

error

return location for errors.

[out callee-allocates][transfer full][allow-none]

Returns

a newly allocated string representing a password which must be freed with g_free(), otherwise NULL is returned and error will be set.

Since 0.8


tracker_password_provider_lock_password ()

gchar *
tracker_password_provider_lock_password
                               (const gchar *password);

This function calls mlock() to secure a memory region newly allocated and password is copied using memcpy() into the new address.

Password can not be NULL or an empty string ("").

Parameters

password

a string pointer

 

Returns

a newly allocated string which MUST be freed with tracker_password_provider_unlock_password(). On failure NULL is returned.

[transfer full]

Since 0.8


tracker_password_provider_store_password ()

gboolean
tracker_password_provider_store_password
                               (TrackerPasswordProvider *provider,
                                const gchar *service,
                                const gchar *description,
                                const gchar *username,
                                const gchar *password,
                                GError **error);

This function calls the password provider's "store_password" implementation with service , description , username and password .

Parameters

provider

a TrackerPasswordProvider

 

service

the name of the remote service associated with username and password

 

description

the description for service

 

username

the username to store

 

password

the password to store

 

error

return location for errors.

[out callee-allocates][transfer full][allow-none]

Returns

TRUE if the password was saved, otherwise FALSE is returned and error will be set.

Since 0.8


tracker_password_provider_unlock_password ()

gboolean
tracker_password_provider_unlock_password
                               (gchar *password);

This function calls munlock() on password which should be a secured memory region. The password is zeroed first with bzero() and once unlocked it is freed with g_free().

The password can not be NULL or an empty string (""). In addition, password MUST be a string created with tracker_password_provider_lock_password().

Parameters

password

a string pointer

 

Returns

TRUE if munlock() succeeded, otherwise FALSE is returned.

Since 0.8

Types and Values

TRACKER_PASSWORD_PROVIDER_ERROR

#define TRACKER_PASSWORD_PROVIDER_ERROR         tracker_password_provider_error_quark()


TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN

#define TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN  "TrackerPasswordProvider"


TrackerPasswordProvider

typedef struct TrackerPasswordProvider TrackerPasswordProvider;


enum TrackerPasswordProviderError

The following errors are possible during any of the performed actions with a password provider.

Members

TRACKER_PASSWORD_PROVIDER_ERROR_SERVICE

An internal error occurred which meant the operation failed.

 

TRACKER_PASSWORD_PROVIDER_ERROR_NOTFOUND

No password provider was found to store/retrieve the remote service's authentication credentials

 

Since 0.8


TrackerPasswordProviderIface

typedef struct {
	GTypeInterface parent_iface;

	gboolean (* store_password)  (TrackerPasswordProvider  *provider,
	                              const gchar              *service,
	                              const gchar              *description,
	                              const gchar              *username,
	                              const gchar              *password,
	                              GError                  **error);
	gchar *  (* get_password)    (TrackerPasswordProvider  *provider,
	                              const gchar              *service,
	                              gchar                   **username,
	                              GError                  **error);
	gboolean (* forget_password) (TrackerPasswordProvider  *provider,
	                              const gchar              *service,
	                              GError                  **error);
} TrackerPasswordProviderIface;

Members

GTypeInterface parent_iface;

parent object interface

 

store_password ()

save the service, username and password

 

get_password ()

get a password for a given service

 

forget_password ()

forget any password associated with a given service

 

Since 0.8