InfdAccountStorage

InfdAccountStorage — Interface to user account database

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <libinfinity/server/infd-account-storage.h>

                    InfdAccountStorage;
struct              InfdAccountStorageIface;
enum                InfdAccountStorageSupport;
InfdAccountStorageSupport infd_account_storage_get_support
                                                        (InfdAccountStorage *storage);
gboolean            infd_account_storage_supports       (InfdAccountStorage *storage,
                                                         InfdAccountStorageSupport support);
InfAclAccount *     infd_account_storage_lookup_accounts
                                                        (InfdAccountStorage *storage,
                                                         const InfAclAccountId *accounts,
                                                         guint n_accounts,
                                                         GError **error);
InfAclAccount *     infd_account_storage_lookup_accounts_by_name
                                                        (InfdAccountStorage *storage,
                                                         const gchar *name,
                                                         guint *n_accounts,
                                                         GError **error);
InfAclAccount *     infd_account_storage_list_accounts  (InfdAccountStorage *storage,
                                                         guint *n_accounts,
                                                         GError **error);
InfAclAccountId     infd_account_storage_add_account    (InfdAccountStorage *storage,
                                                         const gchar *name,
                                                         gnutls_x509_crt_t *certs,
                                                         guint n_certs,
                                                         const gchar *password,
                                                         GError **error);
gboolean            infd_account_storage_remove_account (InfdAccountStorage *storage,
                                                         InfAclAccountId account,
                                                         GError **error);
InfAclAccountId     infd_account_storage_login_by_certificate
                                                        (InfdAccountStorage *storage,
                                                         gnutls_x509_crt_t cert,
                                                         GError **error);
InfAclAccountId     infd_account_storage_login_by_password
                                                        (InfdAccountStorage *storage,
                                                         const gchar *username,
                                                         const gchar *password,
                                                         GError **error);
gboolean            infd_account_storage_set_certificate
                                                        (InfdAccountStorage *storage,
                                                         InfAclAccountId account,
                                                         gnutls_x509_crt_t *certs,
                                                         guint n_certs,
                                                         GError **error);
gboolean            infd_account_storage_set_password   (InfdAccountStorage *storage,
                                                         InfAclAccountId account,
                                                         const gchar *password,
                                                         GError **error);
void                infd_account_storage_account_added  (InfdAccountStorage *storage,
                                                         const InfAclAccount *account);
void                infd_account_storage_account_removed
                                                        (InfdAccountStorage *storage,
                                                         const InfAclAccount *account);

Object Hierarchy

  GInterface
   +----InfdAccountStorage
  GFlags
   +----InfdAccountStorageSupport

Prerequisites

InfdAccountStorage requires GObject.

Known Implementations

InfdAccountStorage is implemented by InfdFilesystemAccountStorage.

Signals

  "account-added"                                  : Run Last
  "account-removed"                                : Run Last

Description

InfdAccountStorage provides an interface for InfdDirectory to access a database of user accounts. It provides methods to list and lookup available accounts, and to add and remove accounts.

Each account is uniquely identified by an account ID, InfAclAccount.id, and is assigned a human-readable name, InfAclAccount.name. Typically, most operations can be performed with the ID, and for example permissions for users are stored by refering to the account ID in InfdDirectory. The authentication storage can be used to look up a name for the ID, and it is responsible for storing the account information permanantly.

Interface implementations do not need to support every operation provided by the API of this interface, however if they support a certain operation, InfdDirectory takes advantage of it. The only required operation is to be able to look up an account name by its ID, and the reverse lookup, i.e. find all accounts with a given name. The InfdAccountStorageIface.get_support() function returns a bitmask of the supported operations.

Implementations of this interface can couple the available accounts to various external sources, such as SQL databases, LDAP or PAM. Libinfinity also provides a standalone implementation of this interface, which stores the account list as a file in the file system, see InfdFilesystemAccountStorage.

Details

InfdAccountStorage

typedef struct _InfdAccountStorage InfdAccountStorage;

InfdAccountStorage is an opaque data type. You should only access it via the public API functions.


struct InfdAccountStorageIface

struct InfdAccountStorageIface {
  InfdAccountStorageSupport (*get_support)(InfdAccountStorage* storage);

  InfAclAccount* (*lookup_accounts)(InfdAccountStorage* storage,
                                    const InfAclAccountId* accounts,
                                    guint n_accounts,
                                    GError** error);

  InfAclAccount* (*lookup_accounts_by_name)(InfdAccountStorage* storage,
                                            const gchar* name,
                                            guint* n_accounts,
                                            GError** error);

  InfAclAccount* (*list_accounts)(InfdAccountStorage* storage,
                                  guint* n_accounts,
                                  GError** error);

  InfAclAccountId (*add_account)(InfdAccountStorage* storage,
                                 const gchar* name,
                                 gnutls_x509_crt_t* certs,
                                 guint n_certs,
                                 const gchar* password,
                                 GError** error);

  gboolean (*remove_account)(InfdAccountStorage* storage,
                             InfAclAccountId account,
                             GError** error);

  InfAclAccountId (*login_by_certificate)(InfdAccountStorage* storage,
                                          gnutls_x509_crt_t cert,
                                          GError** error);

  InfAclAccountId (*login_by_password)(InfdAccountStorage* storage,
                                       const gchar* username,
                                       const gchar* password,
                                       GError** error);

  gboolean (*set_certificate)(InfdAccountStorage* storage,
                              InfAclAccountId account,
                              gnutls_x509_crt_t* certs,
                              guint n_certs,
                              GError** error);

  gboolean (*set_password)(InfdAccountStorage* storage,
                           InfAclAccountId account,
                           const gchar* password,
                           GError** error);

  /* Signals */
  void (*account_added)(InfdAccountStorage* storage,
                        const InfAclAccount* info);

  void (*account_removed)(InfdAccountStorage* storage,
                          const InfAclAccount* info);
};

The virtual methods and default signal handlers of InfdAccountStorage. Implementing these allows an infinote server to set a specific source of user accounts.

get_support ()

Virtual function to get the list of supported operations on the backend.

lookup_accounts ()

Virtual function to look up account by their identifier.

lookup_accounts_by_name ()

Virtual function to reverse-lookup an account identifier when given the account name.

list_accounts ()

Virtual function to obtain a list of all available accounts. Can be NULL if not supported by the backend.

add_account ()

Virtual function to add a new account. Can be NULL if not supported by the backend.

remove_account ()

Virtual function to remove an existing account. Can be NULL if not supported by the backend.

login_by_certificate ()

Virtual function to look up the account associated with a given certificate. Can be NULL if not supported by the backend.

login_by_password ()

Virtual function to check a username and password, and return the associated account. Can be NULL if not supported by the backend.

set_certificate ()

Set the certificate to be associated to a given account, or NULL if not supported.

set_password ()

Set the password for a given account, or NULL if not supported.

account_added ()

Default signal handler for the "account-added" signal.

account_removed ()

Default signal handler for the "account-removed" signal.

enum InfdAccountStorageSupport

typedef enum {
  INFD_ACCOUNT_STORAGE_SUPPORT_NOTIFICATION = 1 << 0,
  INFD_ACCOUNT_STORAGE_SUPPORT_LIST_ACCOUNTS = 1 << 1,
  INFD_ACCOUNT_STORAGE_SUPPORT_ADD_ACCOUNT = 1 << 2,
  INFD_ACCOUNT_STORAGE_SUPPORT_REMOVE_ACCOUNT = 1 << 3,
  INFD_ACCOUNT_STORAGE_SUPPORT_CERTIFICATE_LOGIN = 1 << 4,
  INFD_ACCOUNT_STORAGE_SUPPORT_PASSWORD_LOGIN = 1 << 5,
  INFD_ACCOUNT_STORAGE_SUPPORT_CERTIFICATE_CHANGE = 1 << 6,
  INFD_ACCOUNT_STORAGE_SUPPORT_PASSWORD_CHANGE = 1 << 7
} InfdAccountStorageSupport;

This enumeration specifies operations that might or might not be supported by a particular InfdAccountStorage implementation. Looking up an account by ID or name must always be supported.

INFD_ACCOUNT_STORAGE_SUPPORT_NOTIFICATION

Whether the "account-added" and "account-removed" signals are emitted when accounts are added or removed externally.

INFD_ACCOUNT_STORAGE_SUPPORT_LIST_ACCOUNTS

Whether obtaining a full list of available accounts is supported.

INFD_ACCOUNT_STORAGE_SUPPORT_ADD_ACCOUNT

Whether adding a new account to the storage is supported.

INFD_ACCOUNT_STORAGE_SUPPORT_REMOVE_ACCOUNT

Whether removing an existing account from the storage is supported.

INFD_ACCOUNT_STORAGE_SUPPORT_CERTIFICATE_LOGIN

Whether the account storage supports authenticating users via client certificates.

INFD_ACCOUNT_STORAGE_SUPPORT_PASSWORD_LOGIN

Whether the account storage supports authenticating users via username and password.

INFD_ACCOUNT_STORAGE_SUPPORT_CERTIFICATE_CHANGE

Whether the account storage supports changing the certificate associated to a user.

INFD_ACCOUNT_STORAGE_SUPPORT_PASSWORD_CHANGE

Whether the account storage supports changing a user's password.

infd_account_storage_get_support ()

InfdAccountStorageSupport infd_account_storage_get_support
                                                        (InfdAccountStorage *storage);

Returns a bitmask of operations supported by the account storage backend. If unsupported operations are attempted on storage, an error with code INF_DIRECTORY_ERROR_OPERATION_UNSUPPORTED will be generated.

storage :

A InfdAccountStorage.

Returns :

A bitmask of supported operations.

infd_account_storage_supports ()

gboolean            infd_account_storage_supports       (InfdAccountStorage *storage,
                                                         InfdAccountStorageSupport support);

Checks whether support for all operations specified in support is available for storage. This is equivalent to calling infd_account_storage_get_support() and testing the returned value for containing the bits in support.

storage :

A InfdAccountStorage.

support :

A bitmask of operations to test.

Returns :

TRUE if all operations in support are supported or FALSE otherwise.

infd_account_storage_lookup_accounts ()

InfAclAccount *     infd_account_storage_lookup_accounts
                                                        (InfdAccountStorage *storage,
                                                         const InfAclAccountId *accounts,
                                                         guint n_accounts,
                                                         GError **error);

Looks up the InfAclAccount structure for all IDs present in accounts. The return value is an array of InfAclAccount structures which is in the same order as the accounts array. If an element in the output array has the InfAclAccount.id field set to 0, it means that the account with the corresponding ID in the accounts array does not exist in storage.

storage :

A InfdAccountStorage.

accounts :

An array of InfAclAccountIds to look up.

n_accounts :

The number of elements in accounts.

error :

Location to store error information, if any, or NULL.

Returns :

An array of InfAclAccount structures with n_accounts entries. Free with inf_acl_account_array_free().

infd_account_storage_lookup_accounts_by_name ()

InfAclAccount *     infd_account_storage_lookup_accounts_by_name
                                                        (InfdAccountStorage *storage,
                                                         const gchar *name,
                                                         guint *n_accounts,
                                                         GError **error);

This function performs the "reverse" lookup: Given an account name, the function returns an array with all accounts that have this name. Many backends make sure that there cannot be duplicated names, in which case this can at most return one account, however in principle accounts with the same name are supported.

If there is no account with the given name, the function returns NULL and sets n_accounts to 0. If an error occurs, NULL is returned, n_accounts is undefined, and error is set. Therefore, to reliably find out whether a lookup error occured or this is no account with the given name, a non-NULL error pointer should be passed and checked after the function call.

storage :

A InfdAccountStorage.

name :

The name to look up.

n_accounts :

An output parameter holding the number of returned accounts.

error :

Location to store error information, if any, or NULL.

Returns :

An array of InfAclAccount structures with length n_accounts, or NULL on error or when n_accounts is 0 or error is set. Free with inf_acl_account_array_free().

infd_account_storage_list_accounts ()

InfAclAccount *     infd_account_storage_list_accounts  (InfdAccountStorage *storage,
                                                         guint *n_accounts,
                                                         GError **error);

Returns an array of all accounts in storage. The length of the array is stored in the output parameter n_accounts. The functions returns NULL and sets n_accounts to 0 if there are no accounts in storage. If there is an error, the function returns NULL, n_accounts is undefined, and error is set. Therefore, to reliably find out whether an error occurred or whether there are really no accounts present, a non-NULL error pointer should be passed and checked after the function call.

Note that this function might not be supported by the backend. See infd_account_storage_get_support().

storage :

A InfdAccountStorage.

n_accounts :

An output parameter holding the number of accounts in storage.

error :

Location to store error information, if any, or NULL.

Returns :

An array of InfAclAccount structures with length n_accounts, or NULL if n_accounts is 0 or error is set. Free with inf_acl_account_array_free().

infd_account_storage_add_account ()

InfAclAccountId     infd_account_storage_add_account    (InfdAccountStorage *storage,
                                                         const gchar *name,
                                                         gnutls_x509_crt_t *certs,
                                                         guint n_certs,
                                                         const gchar *password,
                                                         GError **error);

Adds a new account to storage. The account will have the given name. The account ID is determined by the storage backend and if the operation is successful it is returned.

If the operation does not support storing certificates and/or passwords, the function will fail if certs or password are not set to NULL, respectively. Note also that this function might not be supported at all by the backend. See infd_account_storage_get_support().

storage :

A InfdAccountStorage.

name :

The name of the new account.

certs :

An array of certificates that can be used to login to the new account, or NULL.

n_certs :

The length of the certificate array.

password :

A password that can be used to login to the new account, or NULL.

error :

Location to store error information, if any, or NULL.

Returns :

The InfAclAccountId of the added account, or 0 on error.

infd_account_storage_remove_account ()

gboolean            infd_account_storage_remove_account (InfdAccountStorage *storage,
                                                         InfAclAccountId account,
                                                         GError **error);

Removes the account with the given ID from storage.

Note that this function might not be supported by the backend. See infd_account_storage_get_support().

storage :

A InfdAccountStorage.

account :

The ID of the account to remove.

error :

Location to store error information, if any, or NULL.

Returns :

TRUE on success or FALSE on error.

infd_account_storage_login_by_certificate ()

InfAclAccountId     infd_account_storage_login_by_certificate
                                                        (InfdAccountStorage *storage,
                                                         gnutls_x509_crt_t cert,
                                                         GError **error);

This function returns the ID of the account which belongs to the given client certificate. If there is no such account on an error occurs, the function returns 0, and, in the case of an error, error is set as well.

Note that this function might not be supported by the backend. See infd_account_storage_get_support().

storage :

A InfdAccountStorage.

cert :

The certificate presented by the client.

error :

Location to store error information, if any, or NULL.

Returns :

The account ID of the account associated to cert, or 0 on error or if there is no such account.

infd_account_storage_login_by_password ()

InfAclAccountId     infd_account_storage_login_by_password
                                                        (InfdAccountStorage *storage,
                                                         const gchar *username,
                                                         const gchar *password,
                                                         GError **error);

This function returns the account ID which matches to the given username and password. If there is no such account or if the password is incorrect, the function returns 0. If an error occurs, the function returns 0 and error is set.

Note that when the password is incorrect, error is not set. It is only set if there was an internal error and the login procedure could not be carried out due to technical reasons, such as a database outage.

Note that this function might not be supported by the backend. See infd_account_storage_get_support().

storage :

A InfdAccountStorage.

username :

The username of the account to log into.

password :

The password of the corresponding account.

error :

Location to store error information, if any.

Returns :

The account ID of the account associated to username if password is correct, or 0 otherwise.

infd_account_storage_set_certificate ()

gboolean            infd_account_storage_set_certificate
                                                        (InfdAccountStorage *storage,
                                                         InfAclAccountId account,
                                                         gnutls_x509_crt_t *certs,
                                                         guint n_certs,
                                                         GError **error);

Changes the certificate(s) associated to the account with ID account. All certificates that are currently associated to it are removed, and the given certificates are associated instead. If n_certs is 0, there will be no associated certificates and login by certificate will be disabled for account.

Note that this function might not be supported by the backend. See infd_account_storage_get_support().

storage :

A InfdAccountStorage.

account :

The ID of the account whose certificate to set.

certs :

An array of certificates, or NULL if n_certs is 0.

n_certs :

The number of certificates in the certificate array.

error :

Location to store error information, if any.

Returns :

TRUE if the operation was successful or FALSE if an error occured.

infd_account_storage_set_password ()

gboolean            infd_account_storage_set_password   (InfdAccountStorage *storage,
                                                         InfAclAccountId account,
                                                         const gchar *password,
                                                         GError **error);

Changes the password for the account with the given ID. If this call succeeds, the new password will have to be provided to infd_account_storage_login_by_password() for the login to succeed. If password is NULL, the password will be unset and login by password will no longer be possible.

Note that this function might not be supported by the backend. See infd_account_storage_get_support().

storage :

A InfdAccountStorage.

account :

The ID of the account whose password to change.

password :

The new password for the account, or NULL.

error :

Location to store error information, if any, or NULL.

Returns :

TRUE on success or FALSE on error.

infd_account_storage_account_added ()

void                infd_account_storage_account_added  (InfdAccountStorage *storage,
                                                         const InfAclAccount *account);

Emits the "account-added" signal on storage. This should only be used by interface implementations.

storage :

A InfdAccountStorage.

account :

The InfAclAccount that was added to the storage.

infd_account_storage_account_removed ()

void                infd_account_storage_account_removed
                                                        (InfdAccountStorage *storage,
                                                         const InfAclAccount *account);

Emits the "account-removed" signal on storage. This should only be used by interface implementations.

storage :

A InfdAccountStorage.

account :

The InfAclAccount with the account information for the removed account.

Signal Details

The "account-added" signal

void                user_function                      (InfdAccountStorage *storage,
                                                        InfAclAccount      *info,
                                                        gpointer            user_data)      : Run Last

This signal is emitted whenever an account has been added to the account storage. However, the signal is only emitted if the storage implementations supports the INFD_ACCOUNT_STORAGE_SUPPORT_NOTIFICATION support flag.

storage :

The InfdAccountStorage emitting the signal.

info :

The InfAclAccount containing the account ID and account name of the added account.

user_data :

user data set when the signal handler was connected.

The "account-removed" signal

void                user_function                      (InfdAccountStorage *storage,
                                                        InfAclAccount      *info,
                                                        gpointer            user_data)      : Run Last

This signal is emitted whenever an account has been permanently removed from the storage. However, the signal is only emitted if the storage implementations supports the INFD_ACCOUNT_STORAGE_SUPPORT_NOTIFICATION support flag.

storage :

The InfdAccountStorage emitting the signal.

info :

The InfAclAccount containing the account ID and account name of the removed account.

user_data :

user data set when the signal handler was connected.

See Also

InfdDirectory, InfdFilesystemAccountStorage