Top | ![]() |
![]() |
![]() |
![]() |
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 referring 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
InfdAccountStorageInterface.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.
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.
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
.
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 |
||
accounts |
An array of InfAclAccountIds to look up. |
[array length=n_accounts] |
n_accounts |
The number of elements in |
|
error |
Location to store error information, if any, or |
An array of
InfAclAccount structures with n_accounts
entries. Free with
inf_acl_account_array_free()
.
[array length=n_accounts][transfer full]
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 occurred or this is no account with the given name, a non-NULL
error pointer should be passed and checked after the function call.
storage |
||
name |
The name to look up. |
|
n_accounts |
An output parameter holding the number of returned accounts. |
[out] |
error |
Location to store error information, if any, or |
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()
.
[array length=n_accounts][transfer full]
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 |
||
n_accounts |
An output parameter holding the number of accounts
in |
[out] |
error |
Location to store error information, if any, or |
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()
.
[array length=n_accounts][allow-none][transfer full]
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 |
||
name |
The name of the new account. |
|
certs |
An array of certificates that
can be used to login to the new account, or |
[array length=n_certs][allow-none] |
n_certs |
The length of the certificate array. |
|
password |
A password that can be used to login to the
new account, or |
[allow-none] |
error |
Location to store error information, if any, or |
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()
.
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()
.
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()
.
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()
.
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()
.
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.
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.
typedef struct _InfdAccountStorage InfdAccountStorage;
InfdAccountStorage is an opaque data type. You should only access it via the public API functions.
struct InfdAccountStorageInterface { 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* account); void (*account_removed)(InfdAccountStorage* storage, const InfAclAccount* account); };
The virtual methods and default signal handlers of InfdAccountStorage. Implementing these allows an infinote server to set a specific source of user accounts.
Virtual function to get the list of supported operations on the backend. |
||
Virtual function to look up account by their identifier. |
||
Virtual function to reverse-lookup an account identifier when given the account name. |
||
Virtual function to obtain a list of all available accounts.
Can be |
||
Virtual function to add a new account. Can be |
||
Virtual function to remove an existing account. Can be
|
||
Virtual function to look up the account associated
with a given certificate. Can be |
||
Virtual function to check a username and password, and
return the associated account. Can be |
||
Set the certificate to be associated to a given account,
or |
||
Set the password for a given account, or |
||
Default signal handler for the “account-added” signal. |
||
Default signal handler for the “account-removed” signal. |
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.
Whether the “account-added” and “account-removed” signals are emitted when accounts are added or removed externally. |
||
Whether obtaining a full list of available accounts is supported. |
||
Whether adding a new account to the storage is supported. |
||
Whether removing an existing account from the storage is supported. |
||
Whether the account storage supports authenticating users via client certificates. |
||
Whether the account storage supports authenticating users via username and password. |
||
Whether the account storage supports changing the certificate associated to a user. |
||
Whether the account storage supports changing a user's password. |
“account-added”
signalvoid user_function (InfdAccountStorage *storage, InfAclAccount *info, gpointer user_data)
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. |
Flags: Run Last
“account-removed”
signalvoid user_function (InfdAccountStorage *storage, InfAclAccount *info, gpointer user_data)
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. |
Flags: Run Last