Access Control Lists

Access Control Lists — Common data structures for the infinote ACL Permissions

Stability Level

Unstable, unless otherwise indicated

Functions

InfAclAccountId inf_acl_account_id_from_string ()
const gchar * inf_acl_account_id_to_string ()
#define INF_ACL_ACCOUNT_ID_TO_POINTER()
#define INF_ACL_ACCOUNT_POINTER_TO_ID()
InfAclAccount * inf_acl_account_new ()
InfAclAccount * inf_acl_account_copy ()
void inf_acl_account_free ()
void inf_acl_account_array_free ()
InfAclAccount * inf_acl_account_from_xml ()
void inf_acl_account_to_xml ()
InfAclMask * inf_acl_mask_copy ()
void inf_acl_mask_free ()
void inf_acl_mask_clear ()
gboolean inf_acl_mask_empty ()
gboolean inf_acl_mask_equal ()
InfAclMask * inf_acl_mask_set1 ()
InfAclMask * inf_acl_mask_setv ()
InfAclMask * inf_acl_mask_and ()
InfAclMask * inf_acl_mask_and1 ()
InfAclMask * inf_acl_mask_or ()
InfAclMask * inf_acl_mask_or1 ()
InfAclMask * inf_acl_mask_neg ()
gboolean inf_acl_mask_has ()
InfAclSheet * inf_acl_sheet_new ()
InfAclSheet * inf_acl_sheet_copy ()
void inf_acl_sheet_free ()
gboolean inf_acl_sheet_perms_from_xml ()
void inf_acl_sheet_perms_to_xml ()
InfAclSheetSet * inf_acl_sheet_set_new ()
InfAclSheetSet * inf_acl_sheet_set_new_external ()
InfAclSheetSet * inf_acl_sheet_set_copy ()
void inf_acl_sheet_set_free ()
void inf_acl_sheet_set_sink ()
InfAclSheet * inf_acl_sheet_set_add_sheet ()
void inf_acl_sheet_set_remove_sheet ()
InfAclSheetSet * inf_acl_sheet_set_merge_sheets ()
InfAclSheetSet * inf_acl_sheet_set_get_clear_sheets ()
InfAclSheet * inf_acl_sheet_set_find_sheet ()
const InfAclSheet * inf_acl_sheet_set_find_const_sheet ()
InfAclSheetSet * inf_acl_sheet_set_from_xml ()
void inf_acl_sheet_set_to_xml ()

Types and Values

typedef InfAclAccountId
struct InfAclAccount
enum InfAclSetting
struct InfAclMask
struct InfAclSheet
struct InfAclSheetSet
extern const InfAclMask INF_ACL_MASK_ALL
extern const InfAclMask INF_ACL_MASK_DEFAULT
extern const InfAclMask INF_ACL_MASK_LEAF
extern const InfAclMask INF_ACL_MASK_ROOT
extern const InfAclMask INF_ACL_MASK_SUBDIRECTORY

Object Hierarchy

    GBoxed
    ├── InfAclAccount
    ├── InfAclMask
    ├── InfAclSheet
    ╰── InfAclSheetSet
    GEnum
    ╰── InfAclSetting

Includes

#include <libinfinity/common/inf-acl.h>

Description

The basic ACL data structure is InfAclSheet, which represents settings for one user and one node in the infinote directory. One setting can have three states: it can be enabled, it can be disabled or it can be set to default which means to take the setting from the the default account or the parent directory. The default user for the root node must not have any setting set to default.

The various settings are represented by the InfAclSetting enumeration. This specifies different operations for which access can be granted or denied to different users. InfAclMask represents a bitfield of all A InfAclSheetSet represents a set of InfAclSheets, for different users. There is one InfAclSheetSet for each node of a infinote directory.

Usually, for application programming, the functions in this class need not be used. All relevant functionality is exposed by the InfBrowser interface.

Functions

inf_acl_account_id_from_string ()

InfAclAccountId
inf_acl_account_id_from_string (const gchar *id);

Converts the given string into a unique account identifier which can be used with the rest of the ACL API.

Parameters

id

A string representation of an account ID.

 

Returns

The account ID which is equivalent to the given string.

[transfer full]


inf_acl_account_id_to_string ()

const gchar *
inf_acl_account_id_to_string (InfAclAccountId account);

Translates the given account ID to a unique string identifier.

Parameters

account

A InfAclAccountId.

 

Returns

A string representation of the given account ID, or NULL if the account does not exist. The return value must not be freed.


INF_ACL_ACCOUNT_ID_TO_POINTER()

#define             INF_ACL_ACCOUNT_ID_TO_POINTER(id)

Converts a InfAclAccountId to a pointer such that the pointer represents a unique representation of the given ID. The pointer should not be used for anything else except comparisons with other pointer obtained in this way, for example in hash table lookups.

Parameters

id

A InfAclAccountId.

 

INF_ACL_ACCOUNT_POINTER_TO_ID()

#define             INF_ACL_ACCOUNT_POINTER_TO_ID(ptr)

Converts a pointer obtained with INF_ACL_ACCOUNT_ID_TO_POINTER back into the original InfAclAccountId value.

Parameters

ptr

A pointer obtained with INF_ACL_ACCOUNT_ID_TO_POINTER.

 

inf_acl_account_new ()

InfAclAccount *
inf_acl_account_new (InfAclAccountId id,
                     const gchar *name);

Creates a new InfAclAccount.

Parameters

id

The unique ID of the new account.

 

name

The human-readable name of the new account.

[allow-none]

Returns

A new InfAclAccount object.

[transfer full]


inf_acl_account_copy ()

InfAclAccount *
inf_acl_account_copy (const InfAclAccount *account);

Creates a copy of account .

Parameters

account

The InfAclAccount to copy.

 

Returns

A new InfAclAccount. Free with inf_acl_account_free() when no longer needed.

[transfer full]


inf_acl_account_free ()

void
inf_acl_account_free (InfAclAccount *account);

Releases all resources allocated by account .

Parameters

account

A InfAclAccount.

 

inf_acl_account_array_free ()

void
inf_acl_account_array_free (InfAclAccount *accounts,
                            guint n_accounts);

Releases all resources allocated by an array of InfAclAccounts.

Parameters

accounts

An array of InfAclAccount objects.

[array length=n_accounts]

n_accounts

The number of elements in the array.

 

inf_acl_account_from_xml ()

InfAclAccount *
inf_acl_account_from_xml (xmlNodePtr xml,
                          GError **error);

Attempts to deserialize an InfAclAccount that was written to an XML node by the function inf_acl_account_to_xml(). If an error occurs, such as mandatory fields being missing, the function returns NULL and error is set.

Parameters

xml

An XML node.

 

error

Location to store error information, if any.

 

Returns

A new InfAclAccount on success, or NULL on failure. Free with inf_acl_account_free() when no longer needed.

[transfer full]


inf_acl_account_to_xml ()

void
inf_acl_account_to_xml (const InfAclAccount *account,
                        xmlNodePtr xml);

Serializes the properties of account into the XML node xml . The function inf_acl_account_from_xml() does the reverse operation and deserializes the account object from the XML.

Parameters

account

A InfAclAccount.

 

xml

The XML node to write the account attributes to.

 

inf_acl_mask_copy ()

InfAclMask *
inf_acl_mask_copy (const InfAclMask *mask);

Creates a dynamically allocated copy of mask . This function should not usually be used since masks can simply created on the stack and copied by value. This function is mainly meant for the boxed type definition and for language bindings.

Parameters

mask

The InfAclMask to copy.

 

Returns

A new InfAclMask. Free with inf_acl_mask_free() when no longer needed.

[transfer full]


inf_acl_mask_free ()

void
inf_acl_mask_free (InfAclMask *mask);

Releases a InfAclMask that was created with inf_acl_mask_copy().

Parameters

mask

The InfAclMask to free.

 

inf_acl_mask_clear ()

void
inf_acl_mask_clear (InfAclMask *mask);

Resets a mask so that all fields are zero.

Parameters

mask

The InfAclMask to reset.

 

inf_acl_mask_empty ()

gboolean
inf_acl_mask_empty (const InfAclMask *mask);

Checks whether the given mask is empty, i.e. all fields are set to zero.

Parameters

mask

A InfAclMask.

 

Returns

TRUE if mask has all fields zero, or FALSE otherwies.


inf_acl_mask_equal ()

gboolean
inf_acl_mask_equal (const InfAclMask *lhs,
                    const InfAclMask *rhs);

Checks whether the two masks are equal.

Parameters

lhs

The first mask.

 

rhs

The second mask.

 

Returns

TRUE if lhs and rhs are equal or FALSE otherwise.


inf_acl_mask_set1 ()

InfAclMask *
inf_acl_mask_set1 (InfAclMask *mask,
                   const InfAclSetting setting);

Initializes mask such that all permissions are off except the one corresponding to setting .

Parameters

mask

The InfAclMask to initialize.

 

setting

The permission to set.

 

Returns

The mask itself.

[transfer none]


inf_acl_mask_setv ()

InfAclMask *
inf_acl_mask_setv (InfAclMask *mask,
                   const InfAclSetting *settings,
                   guint n_settings);

Initializes mask such that all permissions are off except the ones specified in the settings array.

Parameters

mask

The InfAclMask to initialize.

 

settings

An array of InfAclSettings to set.

[array length=n_settings]

n_settings

The number of settings.

 

Returns

The mask itself.

[transfer none]


inf_acl_mask_and ()

InfAclMask *
inf_acl_mask_and (const InfAclMask *lhs,
                  const InfAclMask *rhs,
                  InfAclMask *out);

Computes the bitwise AND of lhs and rhs and writes the result to out . out is allowed to be equivalent to lhs and/or rhs .

Parameters

lhs

First mask.

 

rhs

Second mask.

 

out

Output mask.

[out]

Returns

The output mask.

[transfer none]


inf_acl_mask_and1 ()

InfAclMask *
inf_acl_mask_and1 (InfAclMask *mask,
                   InfAclSetting setting);

Disables the bit corresponding to setting in mask , leaving all other bits alone.

Parameters

mask

A InfAclMask.

 

setting

The setting to unset.

 

Returns

The mask itself.

[transfer none]


inf_acl_mask_or ()

InfAclMask *
inf_acl_mask_or (const InfAclMask *lhs,
                 const InfAclMask *rhs,
                 InfAclMask *out);

Computes the bitwise OR of lhs and rhs and writes the result to out . out is allowed to be equivalent to lhs and/or rhs .

Parameters

lhs

First mask.

 

rhs

Second mask.

 

out

Output mask.

[out]

Returns

The output mask.

[transfer none]


inf_acl_mask_or1 ()

InfAclMask *
inf_acl_mask_or1 (InfAclMask *mask,
                  InfAclSetting setting);

Enables the bit corresponding to setting in mask , leaving all other bits alone.

Parameters

mask

A InfAclMask.

 

setting

The setting to add.

 

Returns

The mask itself.

[transfer none]


inf_acl_mask_neg ()

InfAclMask *
inf_acl_mask_neg (const InfAclMask *mask,
                  InfAclMask *out);

Negates the given mask bitwise and writes the result to out . The output mask is allowed to be equivalent to mask itself.

Parameters

mask

The mask to negate.

 

out

The output mask.

[out]

Returns

The output mask.

[transfer full]


inf_acl_mask_has ()

gboolean
inf_acl_mask_has (const InfAclMask *mask,
                  InfAclSetting setting);

Returns TRUE if the given mask has the bit which corresponds to setting set, or FALSE otherwise.

Parameters

mask

A InfAclMask.

 

setting

The setting to check.

 

Returns

TRUE if the bit corresponding to setting is set in mask .


inf_acl_sheet_new ()

InfAclSheet *
inf_acl_sheet_new (InfAclAccountId account);

Creates a dynamically allocated InfAclSheet. This is usually not needed because you can copy the structs by value, but it is useful for properties and bindings. The new sheet will hold permissions for the given account. The permissions will initially be all masked out.

Parameters

account

The InfAclAccountId representing a unique account id.

 

Returns

A new InfAclSheet. Free with inf_acl_sheet_free() when no longer in use.

[transfer full]


inf_acl_sheet_copy ()

InfAclSheet *
inf_acl_sheet_copy (const InfAclSheet *sheet);

Makes a dynamically allocated copy of sheet . This should not be used by applications because you can copy the structs by value, but it is useful for properties and bindings.

Parameters

sheet

A InfAclSheet.

 

Returns

A newly-allocated copy of sheet . Free with inf_acl_sheet_free() when no longer in use.

[transfer full]


inf_acl_sheet_free ()

void
inf_acl_sheet_free (InfAclSheet *sheet);

Frees a InfAclSheet allocated by inf_acl_sheet_copy().

Parameters

sheet

A InfAclSheet.

 

inf_acl_sheet_perms_from_xml ()

gboolean
inf_acl_sheet_perms_from_xml (xmlNodePtr xml,
                              InfAclMask *mask,
                              InfAclMask *perms,
                              GError **error);

This function extracts the permission mask and the permission flags from the XML node xml . The counterpart to this function is inf_acl_sheet_perms_to_xml(). If an error occurs the function returns FALSE and error is set.

Parameters

xml

The XML node to read from.

 

mask

Output parameter to write the permission mask to.

[out]

perms

Output parameter to write the permissions to.

[out]

error

Location to store error information, if any.

 

Returns

TRUE if the operation was successful, or FALSE on error.


inf_acl_sheet_perms_to_xml ()

void
inf_acl_sheet_perms_to_xml (const InfAclMask *mask,
                            const InfAclMask *perms,
                            xmlNodePtr xml);

This function writes the given permission mask and permission flags to the XML node xml . They can be converted back using the inf_acl_sheet_perms_from_xml() function.

Parameters

mask

Permission mask to write.

 

perms

Individiual permissions to write.

 

xml

error: Location to store error information, if any.

 

inf_acl_sheet_set_new ()

InfAclSheetSet *
inf_acl_sheet_set_new (void);

Creates a new InfAclSheetSet. Add sheets with inf_acl_sheet_set_add_sheet().

Returns

A new InfAclSheetSet. Free with inf_acl_sheet_set_free().

[transfer full]


inf_acl_sheet_set_new_external ()

InfAclSheetSet *
inf_acl_sheet_set_new_external (const InfAclSheet *sheets,
                                guint n_sheets);

Creates a new InfAclSheetSet refererencing the given ACL sheets. The created sheet set is only holding a reference to the given array, so it must stay alive as long as the sheet set is alive.

No new sheets can be added to the returned sheet set with inf_acl_sheet_set_add_sheet(), or removed with inf_acl_sheet_set_remove_sheet().

Parameters

sheets

An array of InfAclSheets.

[array length=n_sheets]

n_sheets

Number of elements in sheets .

 

Returns

A new InfAclSheetSet. Free with inf_acl_sheet_set_free() when no longer needed.

[transfer full]


inf_acl_sheet_set_copy ()

InfAclSheetSet *
inf_acl_sheet_set_copy (const InfAclSheetSet *sheet_set);

Creates a copy of sheet_set . If sheet_set was created with inf_acl_sheet_set_new_external(), the copied sheet set will also only hold a reference to the external sheets, and the same restrictions apply.

Parameters

sheet_set

A InfAclSheetSet.

 

Returns

A new InfAclSheetSet. Free with inf_acl_sheet_set_free() when no longer needed.

[transfer full]


inf_acl_sheet_set_free ()

void
inf_acl_sheet_set_free (InfAclSheetSet *sheet_set);

Releases all resources allocated for sheet_set .

Parameters

sheet_set

A InfAclSheetSet.

 

inf_acl_sheet_set_sink ()

void
inf_acl_sheet_set_sink (InfAclSheetSet *sheet_set);

If a sheet set was created with inf_acl_sheet_set_new_external(), this function lifts the restrictions that come with it by making an internal copy of the ACL sheets.

Parameters

sheet_set

A InfAclSheetSet.

 

inf_acl_sheet_set_add_sheet ()

InfAclSheet *
inf_acl_sheet_set_add_sheet (InfAclSheetSet *sheet_set,
                             InfAclAccountId account);

Adds a new default sheet for account to sheet_set . The function returns a pointer to the new sheet. The pointer stays valid as long as no other sheet is added to the set. If there is already a sheet for account in the set, then the existing sheet is returned instead.

This function can only be used if the sheet set has not been created with the inf_acl_sheet_set_new_external() function.

Parameters

sheet_set

A InfAclSheetSet.

 

account

The InfAclAccountId representing a unique account ID.

 

Returns

A InfAclSheet for the new account.

[transfer none]


inf_acl_sheet_set_remove_sheet ()

void
inf_acl_sheet_set_remove_sheet (InfAclSheetSet *sheet_set,
                                InfAclSheet *sheet);

Removes a sheet from sheet_set . sheet must be one of the sheets inside sheet_set . The sheet is removed by replacing it with the last sheet in the set, so the order of sheets is not preserved.

This function can only be used if the sheet set has not been created with the inf_acl_sheet_set_new_external() function.

Parameters

sheet_set

A InfAclSheetSet.

 

sheet

The sheet to remove.

 

inf_acl_sheet_set_merge_sheets ()

InfAclSheetSet *
inf_acl_sheet_set_merge_sheets (InfAclSheetSet *sheet_set,
                                const InfAclSheetSet *other);

Replaces all sheets that are present in other in sheet_set with the ones from other . Note that an empty sheet in other (with all permissions masked out) causes the corresponding sheet in sheet_set to be removed.

If sheet_set is NULL it is treated like an empty sheet set, i.e. the merged sheet set is a copy of other . In that case a new sheet set is created and returned, unless other is empty. If the merged sheet set ends up empty, it is freed and the function returns NULL.

Parameters

sheet_set

A InfAclSheetSet, or NULL.

[allow-none][transfer full]

other

The sheet set to merge.

 

Returns

The merged sheet set, or NULL when the merged sheet set would be empty.

[allow-none][transfer full]


inf_acl_sheet_set_get_clear_sheets ()

InfAclSheetSet *
inf_acl_sheet_set_get_clear_sheets (const InfAclSheetSet *sheet_set);

Returns a new sheet set with all sheets that are present in sheet_set , but with all permissions masked. When this set is merged with the original set, all permissions will be reset to default for all accounts. Before the merge, the returned sheet set can be modified. This allows to replace the current permissions with new ones atomically.

Parameters

sheet_set

A InfAclSheetSet.

 

Returns

A new InfAclSheetSet. Free with inf_acl_sheet_set_free() when no longer needed.

[transfer full]


inf_acl_sheet_set_find_sheet ()

InfAclSheet *
inf_acl_sheet_set_find_sheet (InfAclSheetSet *sheet_set,
                              InfAclAccountId account);

Returns the InfAclSheet for account . If there is no such sheet in sheet_set , the function returns NULL.

This function can only be used if the sheet set has not been created with the inf_acl_sheet_set_new_external() function.

Parameters

sheet_set

A InfAclSheetSet.

 

account

The InfAclAccountId representing the unique account ID of the account whose ACL sheet is to be found.

 

Returns

A InfAclSheet for account , or NULL.

[transfer none]


inf_acl_sheet_set_find_const_sheet ()

const InfAclSheet *
inf_acl_sheet_set_find_const_sheet (const InfAclSheetSet *sheet_set,
                                    InfAclAccountId account);

Returns the InfAclSheet for account . If there is no such sheet in sheet_set , the function returns NULL.

The difference between this function and inf_acl_sheet_set_find_sheet() is that this function returns a sheet that cannot be modified, but it can also be used on a sheet set created with the inf_acl_sheet_set_new_external() function.

Parameters

sheet_set

A InfAclSheetSet.

 

account

The InfAclAccountId representing the unique account ID of the account whose ACL sheet is to be found.

 

Returns

A InfAclSheet for account , or NULL.

[transfer none]


inf_acl_sheet_set_from_xml ()

InfAclSheetSet *
inf_acl_sheet_set_from_xml (xmlNodePtr xml,
                            GError **error);

Reads a sheet set from xml that has been written with inf_acl_sheet_set_to_xml(). If an error occurs the function returns NULL and error is set. If there is no ACL stored in xml , the function returns NULL without setting error .

Parameters

xml

The XML node from which to read the sheet set.

 

error

Location to read error information, if any.

 

Returns

A InfAclSheetSet, or NULL. Free with inf_acl_sheet_set_free() when no longer needed.

[transfer full]


inf_acl_sheet_set_to_xml ()

void
inf_acl_sheet_set_to_xml (const InfAclSheetSet *sheet_set,
                          xmlNodePtr xml);

Serializes the sheet set given by sheet_set into an XML node. The sheet set can be deserialized again with inf_acl_sheet_set_from_xml().

Parameters

sheet_set

The InfAclSheetSet to serialize.

 

xml

The XML node to serialize sheet_set into.

 

Types and Values

InfAclAccountId

typedef GQuark InfAclAccountId;

This type represents a unique identifier for a user account.


struct InfAclAccount

struct InfAclAccount {
  InfAclAccountId id;
  gchar* name;
};

This boxed type specifies basic user account information.

Members

InfAclAccountId id;

A unique ID for this account.

 

gchar *name;

A human readable account name.

 

enum InfAclSetting

Defines the actual permissions that can be granted or revoked for different users.

Members

INF_ACL_CAN_ADD_SUBDIRECTORY

The user is allowed to create a new subdirectory node.

 

INF_ACL_CAN_ADD_DOCUMENT

The user is allowed to create a new leaf node.

 

INF_ACL_CAN_SYNC_IN

The user is allowed to create documents with non-empty content.

 

INF_ACL_CAN_REMOVE_NODE

The user is allowed to remove a child node.

 

INF_ACL_CAN_EXPLORE_NODE

The user is allowed to explore a subdirectory node in the directory tree.

 

INF_ACL_CAN_SUBSCRIBE_CHAT

The user can subscribe to the global server-wide chat.

 

INF_ACL_CAN_SUBSCRIBE_SESSION

The user is allowed to subscribe to a session in the directory tree.

 

INF_ACL_CAN_JOIN_USER

The user is allowed to join a user into the session which corresponds to the node.

 

INF_ACL_CAN_QUERY_ACCOUNT_LIST

The user is allowed to query the full list of ACL accounts.

 

INF_ACL_CAN_CREATE_ACCOUNT

The user can create a new account on the server.

 

INF_ACL_CAN_OVERRIDE_ACCOUNT

The user can create an account under a name that exists already, overriding the login credentials.

 

INF_ACL_CAN_REMOVE_ACCOUNT

The user can remove user accounts.

 

INF_ACL_CAN_QUERY_ACL

The user is allowed to query the full ACL for this node.

 

INF_ACL_CAN_SET_ACL

The user is allowed to change the ACL of this node, or create new nodes with a non-default ACL.

 

struct InfAclMask

struct InfAclMask {
  /* leave quite some space for future use */
  guint64 mask[4];
};

This structure represents a mask of InfAclSettings, where each setting can be either turned on or off.

Members

guint64 mask[4];

A 256 bit wide bitfield of InfAclSettings.

 

struct InfAclSheet

struct InfAclSheet {
  InfAclAccountId account;
  InfAclMask mask;
  InfAclMask perms;
};

A set of permissions to be applied for a particular account and a particular node in the infinote directory.

Members

InfAclAccountId account;

The account for which to apply the permissions in this sheet.

 

InfAclMask mask;

Mask which specifies which of the permissions in the perms field take effect. Fields which are masked-out are left at their default value and inherited from the parent node.

 

InfAclMask perms;

Mask which specifies whether or not the user is allowed to perform the various operations defined by InfAclSetting.

 

struct InfAclSheetSet

struct InfAclSheetSet {
  const InfAclSheet* sheets;
  guint n_sheets;
};

A set of InfAclSheets, one for each user.

Members

const InfAclSheet *sheets;

An array of InfAclSheet objects.

 

guint n_sheets;

The number of elements in the sheets array.

 

INF_ACL_MASK_ALL

extern const InfAclMask INF_ACL_MASK_ALL;

INF_ACL_MASK_DEFAULT

extern const InfAclMask INF_ACL_MASK_DEFAULT;

INF_ACL_MASK_LEAF

extern const InfAclMask INF_ACL_MASK_LEAF; /* only applicable for leaf node */

INF_ACL_MASK_ROOT

extern const InfAclMask INF_ACL_MASK_ROOT; /* only applicable for root node */

INF_ACL_MASK_SUBDIRECTORY

extern const InfAclMask INF_ACL_MASK_SUBDIRECTORY; /* only applicable for subdirectory node */

See Also

InfBrowser