EAuthenticationSession

EAuthenticationSession — Centralized authentication management

Functions

Properties

ESourceAuthenticator * authenticator Read / Write / Construct Only
gchar * prompt-description Read / Write
gchar * prompt-message Read / Write
gchar * prompt-title Read / Write
ESourceRegistryServer * server Read / Write / Construct Only
gchar * source-uid Read / Write / Construct Only

Types and Values

Object Hierarchy

    GObject
    ╰── EAuthenticationSession

Includes

#include <libebackend/libebackend.h>

Description

EAuthenticationSession provides centralized password management and password prompting for all clients of the registry D-Bus service.

An EAuthenticationSession is created within the registry D-Bus service when the service receives a request to authenticate some data source. Clients can issue requests by calling e_source_registry_authenticate(). Requests can also come from any ECollectionBackend running within the service itself.

An EAuthenticationSession requires some object implementing the ESourceAuthenticator interface to verify stored or user-provided passwords. EAuthenticationMediator is used for client-issued authentication requests. Custom collection backends derived from ECollectionBackend usually implement the ESourceAuthenticator interface themselves.

The EAuthenticationSession is then handed to ESourceRegistryServer through e_source_registry_server_authenticate() where it waits in line behind other previously added authentication sessions. When its turn comes, the server calls e_authentication_session_execute() to begin the interactive authentication session.

Functions

e_authentication_session_get_server ()

struct _ESourceRegistryServer *
e_authentication_session_get_server (EAuthenticationSession *session);

Returns the ESourceRegistryServer to which session belongs.

Parameters

session

an EAuthenticationSession

 

Returns

the ESourceRegistryServer for session

Since 3.6


e_authentication_session_get_authenticator ()

ESourceAuthenticator *
e_authentication_session_get_authenticator
                               (EAuthenticationSession *session);

Returns the ESourceAuthenticator handling authentication attempts for session . This is usually an EAuthenticationMediator but can also be a custom collection backend derived from ECollectionBackend.

Parameters

session

an EAuthenticationSession

 

Returns

the ESourceAuthenticator for session

Since 3.6


e_authentication_session_get_source_uid ()

const gchar *
e_authentication_session_get_source_uid
                               (EAuthenticationSession *session);

Returns the “uid” of the authenticating data source. The data source may or may not be known to the “server”.

Parameters

session

an EAuthenticationSession

 

Returns

the UID of the authenticating data source

Since 3.6


e_authentication_session_get_prompt_title ()

const gchar *
e_authentication_session_get_prompt_title
                               (EAuthenticationSession *session);

Returns the text used for the password prompt title should prompting be necessary. See GcrPrompt for more details about password prompts.

Parameters

session

an EAuthenticationSession

 

Returns

the password prompt title

Since 3.6


e_authentication_session_dup_prompt_title ()

gchar *
e_authentication_session_dup_prompt_title
                               (EAuthenticationSession *session);

Thread-safe variation of e_authentication_session_get_prompt_title(). Use this function when accessing session from multiple threads.

The returned string should be freed with g_free() when no longer needed.

Parameters

session

an EAuthenticationSession

 

Returns

a newly-allocated copy of “prompt-title”

Since 3.6


e_authentication_session_set_prompt_title ()

void
e_authentication_session_set_prompt_title
                               (EAuthenticationSession *session,
                                const gchar *prompt_title);

Sets the text used for the password prompt title should prompting be necessary. See GcrPrompt for more details about password prompts.

Parameters

session

an EAuthenticationSession

 

prompt_title

the password prompt title, or NULL

 

Since 3.6


e_authentication_session_get_prompt_message ()

const gchar *
e_authentication_session_get_prompt_message
                               (EAuthenticationSession *session);

Returns the text used for the password prompt message should prompting be necessary. See GcrPrompt for more details about password prompts.

Parameters

session

an EAuthenticationSession

 

Returns

the password prompt message

Since 3.6


e_authentication_session_dup_prompt_message ()

gchar *
e_authentication_session_dup_prompt_message
                               (EAuthenticationSession *session);

Thread-safe variation of e_authentication_session_get_prompt_message(). Use this function when accessing session from multiple threads.

The returned string should be freed with g_free() when no longer needed.

Parameters

session

an EAuthenticationSession

 

Returns

a newly-allocated copy of “prompt-message”

Since 3.6


e_authentication_session_set_prompt_message ()

void
e_authentication_session_set_prompt_message
                               (EAuthenticationSession *session,
                                const gchar *prompt_message);

Sets the text used for the password prompt message should prompting be necessary. See GcrPrompt for more details about password prompts.

Parameters

session

an EAuthenticationSession

 

prompt_message

the password prompt message, or NULL

 

Since 3.6


e_authentication_session_get_prompt_description ()

const gchar *
e_authentication_session_get_prompt_description
                               (EAuthenticationSession *session);

Returns the text used for the password prompt description should prompting be necessary. See GcrPrompt for more details about password prompts.

Parameters

session

an EAuthenticationSession

 

Returns

the password prompt description

Since 3.6


e_authentication_session_dup_prompt_description ()

gchar *
e_authentication_session_dup_prompt_description
                               (EAuthenticationSession *session);

Thread-safe variation of e_authentication_session_get_prompt_description(). Use this function when accessing session from multiple threads.

The returned string should be freed with g_free() when no longer needed.

Parameters

session

an EAuthenticationSession

 

Returns

a newly-allocated copy of “prompt-description”

Since 3.6


e_authentication_session_set_prompt_description ()

void
e_authentication_session_set_prompt_description
                               (EAuthenticationSession *session,
                                const gchar *prompt_description);

Sets the text used for the password prompt description should prompting be necessary. See GcrPrompt for more details about password prompts.

Parameters

session

an EAuthenticationSession

 

prompt_description

the password prompt description

 

Since 3.6


e_authentication_session_execute_sync ()

EAuthenticationSessionResult
e_authentication_session_execute_sync (EAuthenticationSession *session,
                                       GCancellable *cancellable,
                                       GError **error);

Executes an authentication session.

First the secret service is queried for a stored password. If found, an authentication attempt is made without disturbing the user. If no stored password is found, or if the stored password is rejected, the user is shown a system-modal dialog requesting a password. Further authentication attempts are repeated with user-provided passwords until authentication is verified or the user dismisses the prompt. The returned EAuthenticationSessionResult indicates the outcome.

If an error occurs while interacting with the secret service, or while prompting the user for a password, or while attempting authentication, the function sets error and returns E_AUTHENTICATION_SESSION_ERROR.

Parameters

session

an EAuthenticationSession

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

the result of the authentication session

Since 3.6


e_authentication_session_execute ()

void
e_authentication_session_execute (EAuthenticationSession *session,
                                  gint io_priority,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

See e_authentication_session_execute_sync() for details.

When the operation is finished, callback will be called. You can then call e_authentication_session_execute_finish() to get the result of the operation.

Parameters

session

an EAuthenticationSession

 

io_priority

the I/O priority of the request

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since 3.6


e_authentication_session_execute_finish ()

EAuthenticationSessionResult
e_authentication_session_execute_finish
                               (EAuthenticationSession *session,
                                GAsyncResult *result,
                                GError **error);

Finishes the operation started with e_authentication_session_execute().

If an error occurs while interacting with the secret service, or while prompting the user for a password, or while attempting authentication, the function sets error and returns E_AUTHENTICATION_SESSION_ERROR.

Parameters

session

an EAuthenticationSession

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

the result of the authentication session

Since 3.6


e_authentication_session_store_password_sync ()

gboolean
e_authentication_session_store_password_sync
                               (EAuthenticationSession *session,
                                const gchar *password,
                                gboolean permanently,
                                GCancellable *cancellable,
                                GError **error);

Store a password for the data source that session is representing. If permanently is TRUE, the password is stored in the default keyring. Otherwise the password is stored in the memory-only session keyring. If an error occurs, the function sets error and returns FALSE.

Parameters

session

an EAuthenticationSession

 

password

the password to store

 

permanently

store permanently or just for the session

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error

Since 3.6


e_authentication_session_store_password ()

void
e_authentication_session_store_password
                               (EAuthenticationSession *session,
                                const gchar *password,
                                gboolean permanently,
                                gint io_priority,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously stores a password for the data source that session is representing. If permanently is TRUE, the password is stored in the default keyring. Otherwise the password is stored in the memory-only session keyring.

When the operation is finished, callback will be called. You can then call e_authentication_session_store_password_finish() to get the result of the operation.

Parameters

session

an EAuthenticationSession

 

password

the password to store

 

permanently

store permanently or just for the session

 

io_priority

the I/O priority of the request

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since 3.6


e_authentication_session_store_password_finish ()

gboolean
e_authentication_session_store_password_finish
                               (EAuthenticationSession *session,
                                GAsyncResult *result,
                                GError **error);

Finished the operation started with e_authentication_session_store_password().

Parameters

session

an EAuthenticationSession

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error

Since 3.6


e_authentication_session_lookup_password_sync ()

gboolean
e_authentication_session_lookup_password_sync
                               (EAuthenticationSession *session,
                                GCancellable *cancellable,
                                gchar **password,
                                GError **error);

Looks up a password for the data source that session is representing. Both the default and session keyrings are queried.

Note the boolean return value indicates whether the lookup operation itself completed successfully, not whether a password was found. If no password was found, the function will set password to NULL but still return TRUE. If an error occurs, the function sets error and returns FALSE.

Parameters

session

an EAuthenticationSession

 

cancellable

optional GCancellable object, or NULL

 

password

return location for the password, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error

Since 3.6


e_authentication_session_lookup_password ()

void
e_authentication_session_lookup_password
                               (EAuthenticationSession *session,
                                gint io_priority,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously looks up a password for the data source that session is representing. Both the default and session keyrings are queried.

When the operation is finished, callback will be called. You can then call e_authentication_session_lookup_password_finish() to get the result of the operation.

Parameters

session

an EAuthenticationSession

 

io_priority

the I/O priority of the request

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since 3.6


e_authentication_session_lookup_password_finish ()

gboolean
e_authentication_session_lookup_password_finish
                               (EAuthenticationSession *session,
                                GAsyncResult *result,
                                gchar **password,
                                GError **error);

Finishes the operation started with e_authentication_session_lookup_password().

Note the boolean return value indicates whether the lookup operation itself completed successfully, not whether a password was found. If no password was found, the function will set password to NULL but still return TRUE. If an error occurs, the function sets error and returns FALSE.

Parameters

session

an EAuthenticationSession

 

result

a GAsyncResult

 

password

return location for the password, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error

Since 3.6


e_authentication_session_delete_password_sync ()

gboolean
e_authentication_session_delete_password_sync
                               (EAuthenticationSession *session,
                                GCancellable *cancellable,
                                GError **error);

Deletes the password for the data source that session is representing from either the default keyring or session keyring.

Note the boolean return value indicates whether the delete operation itself completed successfully, not whether a password was found and deleted. If no password was found, the function will still return TRUE. If an error occurs, the function sets error and returns FALSE.

Parameters

session

an EAuthenticationSession

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error

Since 3.6


e_authentication_session_delete_password ()

void
e_authentication_session_delete_password
                               (EAuthenticationSession *session,
                                gint io_priority,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asyncronously deletes the password for the data source that session is representing from either the default keyring or session keyring.

When the operation is finished, callback will be called. You can then call e_authentication_session_delete_password_finish() to get the result of the operation.

Parameters

session

an EAuthenticationSession

 

io_priority

the I/O priority of the request

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since 3.6


e_authentication_session_delete_password_finish ()

gboolean
e_authentication_session_delete_password_finish
                               (EAuthenticationSession *session,
                                GAsyncResult *result,
                                GError **error);

Finishes the operation started with e_authentication_session_delete_password().

Note the boolean return value indicates whether the delete operation itself completed successfully, not whether a password was found and deleted. If no password was found, the function will still return TRUE. If an error occurs, the function sets error and returns FALSE.

Parameters

session

an EAuthenticationSession

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error

Since 3.6


e_authentication_session_new ()

EAuthenticationSession *
e_authentication_session_new (struct _ESourceRegistryServer *server,
                              ESourceAuthenticator *authenticator,
                              const gchar *source_uid);

e_authentication_session_new has been deprecated since version 3.8 and should not be used in newly-written code.

Use e_source_registry_server_new_auth_session() instead.

Creates a new EAuthenticationSession instance for server using authenticator to handle authentication attempts.

Note that source_uid does not necessarily have to be known to the server , as in the case when configuring a new data source, but it still has to be unique.

Parameters

server

an ESourceRegistryServer

 

authenticator

an ESourceAuthenticator

 

source_uid

a data source identifier

 

Returns

a newly-created EAuthenticationSession

Since 3.6

Types and Values

struct EAuthenticationSession

struct EAuthenticationSession;

Contains only private data that should be read and manipulated using the functions below.

Since 3.6


enum EAuthenticationSessionResult

Completion codes used by EAuthenticationSession.

Members

E_AUTHENTICATION_SESSION_ERROR

An error occurred while authenticating.

 

E_AUTHENTICATION_SESSION_SUCCESS

Client reported successful authentication.

 

E_AUTHENTICATION_SESSION_DISMISSED

User dismissed the authentication prompt.

 

Since 3.6


E_AUTHENTICATION_SESSION_KEYRING_ERROR

#define             E_AUTHENTICATION_SESSION_KEYRING_ERROR

E_AUTHENTICATION_SESSION_KEYRING_ERROR has been deprecated since version 3.8 and should not be used in newly-written code.

The SECRET_ERROR domain is now used instead.

Error domain for password storage and retrieval.

No longer used.

Since 3.6

Property Details

The “authenticator” property

  “authenticator”            ESourceAuthenticator *

Handles authentication attempts.

Flags: Read / Write / Construct Only


The “prompt-description” property

  “prompt-description”       gchar *

The detailed description of the prompt.

Flags: Read / Write

Default value: NULL


The “prompt-message” property

  “prompt-message”           gchar *

The prompt message for the user.

Flags: Read / Write

Default value: NULL


The “prompt-title” property

  “prompt-title”             gchar *

The title of the prompt.

Flags: Read / Write

Default value: NULL


The “server” property

  “server”                   ESourceRegistryServer *

The server to which the session belongs.

Flags: Read / Write / Construct Only


The “source-uid” property

  “source-uid”               gchar *

Unique ID of the data source being authenticated.

Flags: Read / Write / Construct Only

Default value: NULL