Collaboration diagram for Actor Access Operations:

Functions
bool	access_actor_general (const a2id_t current_id, const a2id_t requested_id, const uint8_t opt_svckey_group, unsigned svckeygrouplen, const char opt_grouprules, unsigned groupruleslen, const uint8_t opt_svckey_pseudo, unsigned svckeypseudolen, const char opt_pseudorules, unsigned pseudoruleslen)
	Generic check if a user may act from another identity. More...

static bool	access_actor (const a2id_t current_id, const a2id_t requested_id)
	Straightforward check if a user may act from another identity. More...

static bool	access_actor_svckey (const a2id_t current_id, const a2id_t requested_id, const uint8_t svckey_group, unsigned svckeygrouplen, const uint8_t svckey_pseudo, unsigned svckeypseudolen)
	Service-Key-based check if a user may act from another identity. More...

static bool	access_actor_ruleset (const a2id_t current_id, const a2id_t requested_id, const char grouprules, unsigned groupruleslen, const char pseudorules, unsigned pseudoruleslen)
	Rules-based check if a user may act from another identity. More...

bool	access_actor_pseudonym (const a2id_t current_id, const a2id_t requested_id, const uint8_t opt_svckey_pseudo, unsigned svckeypseudolen, const char opt_pseudorules, unsigned pseudoruleslen, access_rights *out_rights)
	Test the rights for a switch from current_id to a pseudonym. More...

Detailed Description

Actor Access determines whether a user with a known identity may take on another identity, a so-called Actor Identity. This may be used to substitute a login identity for one that has another acl profile, for instance because it is part of a group.

Actor Access has no Access Type of its own; it relies on the service keys for groups and pseudonyms (and on their usual defaults).

Function Documentation

◆ access_actor()

static bool access_actor	(	const a2id_t *	current_id,
		const a2id_t *	requested_id
	)

inlinestatic

Straightforward check if a user may act from another identity.

This is a variant of access_actor_general() intended for the use of an unencrypted Rules DB. This is a nice initial method, but should normally evolve into a more fully supportive version based on access_actor_svckey().

Parameters

[in]	current_id	is the identity that has been validated through authentication and possible preceding calls to access_actor().
[in]	requested_id	is the identity that the user is asking to use in subsequent actions. When approved, this will take the place of current_id.

Returns: When the requested_id may replace the current_id then true is returned, otherwise false.

◆ access_actor_general()

bool access_actor_general	(	const a2id_t *	current_id,
		const a2id_t *	requested_id,
		const uint8_t *	opt_svckey_group,
		unsigned	svckeygrouplen,
		const char *	opt_grouprules,
		unsigned	groupruleslen,
		const uint8_t *	opt_svckey_pseudo,
		unsigned	svckeypseudolen,
		const char *	opt_pseudorules,
		unsigned	pseudoruleslen
	)

Generic check if a user may act from another identity.

Functions with simpler signatures for simpler use cases are available as access_actor() and access_actor_svckey(). It is ILL-ADVISED to use the explicit rulesets in this one.

Users have authenticated to obtain an (initial) identity, and may optionally step to other identities from there. During this process, they are assigned a new identity, sometimes referred to as their Actor Identity. It will replace the original identity, and be further considered as if it was the original identity. It may for instance be used for logging, for additional access_actor() calls but also in other Access Control calls.

It will often suffice to fill only the first two parameters and fill the rest with NULL and 0 values, and to check the return value for approval.

Parameters

[in]	current_id	is the identity that has been validated through authentication and possible preceding calls to access_actor().
[in]	requested_id	is the identity that the user is asking to use in subsequent actions. When approved, this will take the place of current_id.
[in]	opt_svckey_group	may be NULL or a Service Key for group database access. When set to NULL, the default is used.
[in]	svckeygrouplen	specifies the length in bytes of the opt_svckey_group. It is only meaningful when that is not NULL.
[in]	opt_grouprules	may be NULL or a concatenation of zero-terminated strings with rules for the group. When not NULL, it is an alternative to the opt_svckey parameter.
[in]	groupruleslen	is the total length of opt_grouprules in bytes, including the very last zero terminator.
[in]	opt_svckey_pseudo	may be NULL or a Service Key for pseudonym database access. When set to NULL, the default is used.
[in]	svckeypseudolen	specifies the length in bytes of the opt_svckey_pseudo. It is only meaningful when that is not NULL.
[in]	opt_pseudorules	may be NULL or a concatenation of zero-terminated strings with rules for the group. When not NULL, it is an alternative to the opt_svckey_pseudo parameter.
[in]	pseudoruleslen	is the total length of opt_pseudorules, strings, in bytes, including the very last zero terminator.

Returns: When the requested_id may replace the current_id then true is returned, otherwise false.

◆ access_actor_pseudonym()

bool access_actor_pseudonym	(	const a2id_t *	current_id,
		const a2id_t *	requested_id,
		const uint8_t *	opt_svckey_pseudo,
		unsigned	svckeypseudolen,
		const char *	opt_pseudorules,
		unsigned	pseudoruleslen,
		access_rights *	out_rights
	)

Test the rights for a switch from current_id to a pseudonym.

This function evaluates a ruleset for Pseudonym Actor Access, and returns the Acess Rights found. Usually this consists of ACCESS_OPERATE or T and possible ACCESS_ADMIN or A, where the former allows the switch to the pseudonym and the latter grants changes to who may use the pseudonym. Very often, both flags will be assigned together.

Parameters

[in]	current_id	is the identity that has been validated through authentication and possible preceding calls to access_actor(). It may be foreign and is therefore assumed to have been parsed with a2id_parse_remote() rather than a2id_parse(). If it is a local identity, it should not be a service identity (starting with a `+` character). It is not common to include later `+` characters in the user name, but it may be used if so desired.
[in]	requested_id	is the pseudonym that the user is trying to use in subsequent actions. This may or may not have aliases, but any database lookups would not involve user name aliases. This is a local name and is assumed to have been parsed with a2id_parse().
[in]	opt_svckey_pseudo	may be NULL or a Service Key for pseudonym database access. When set to NULL, the default is used.
[in]	svckeypseudolen	specifies the length in bytes of the opt_svckey_pseudo. It is only meaningful when that is not NULL.
[in]	opt_pseudorules	may be NULL or a concatenation of zero-terminated strings with rules for the group. When not NULL, it is an alternative to the opt_svckey_pseudo parameter.
[in]	pseudoruleslen	is the total length of opt_pseudorules, strings, in bytes, including the very last zero terminator.
[out]	out_rights	is set to the Access Rights according to the policy for the pseudonym in the requested_id. It is meaningful even when the return value is false, which case it only holds ACCESS_VISITOR or V. When a pseudonym was found, then any Access Rules that made it to the end of any rule in the ruleset are combined with that basic result. Usually, this means that ACCESS_OEPRATE or T is added to grant the use of the pseudonym, and/or that ACCESS_ADMIN or A is added to grant changes to the people who may change the current_id values permitted for the pseudonym.

Returns: true only when the Policy Rule for the Pseudonym in the requested_id was found and evaluated properly, regardless of value, or false otherwise.

◆ access_actor_ruleset()

static bool access_actor_ruleset	(	const a2id_t *	current_id,
		const a2id_t *	requested_id,
		const char *	grouprules,
		unsigned	groupruleslen,
		const char *	pseudorules,
		unsigned	pseudoruleslen
	)

inlinestatic

Rules-based check if a user may act from another identity.

This is an ILL-ADVISED variant of access_actor_general() intended for the use of rules outside of a database. The reason that this variant is not advised is that it avoids sytem-wide integrated use of groups and pseudonyms, as designed for the InternetWide Architecture.

Advised variants are access_actor() for simple uses, and access_actor_svckey().

If you need to mix Service Key with supplied Rules, please use access_actor_general() instead. This is also ill-advised.

Parameters

[in]	current_id	is the identity that has been validated through authentication and possible preceding calls to access_actor().
[in]	requested_id	is the identity that the user is asking to use in subsequent actions. When approved, this will take the place of current_id.
[in]	grouprules	is a concatenation of zero-terminated strings with rules for the group.
[in]	groupruleslen	is the total length of opt_grouprules in bytes, including the very last zero terminator.
[in]	pseudorules	is a concatenation of zero-terminated strings with rules for the group.
[in]	pseudoruleslen	is the total length of opt_pseudorules, strings, in bytes, including the very last zero terminator.

Returns: When the requested_id may replace the current_id then true is returned, otherwise false.

◆ access_actor_svckey()

static bool access_actor_svckey	(	const a2id_t *	current_id,
		const a2id_t *	requested_id,
		const uint8_t *	svckey_group,
		unsigned	svckeygrouplen,
		const uint8_t *	svckey_pseudo,
		unsigned	svckeypseudolen
	)

inlinestatic

Service-Key-based check if a user may act from another identity.

This is a variant of access_actor_general() intended for the use of an encrypted Rules DB. This is the step up from access_actor() that allows it to work with more secure environments, such as plugin services hosted away from the identity provider, and supplied only with information on a need-to-know basis.

Parameters

[in]	current_id	is the identity that has been validated through authentication and possible preceding calls to access_actor().
[in]	requested_id	is the identity that the user is asking to use in subsequent actions. When approved, this will take the place of current_id.
[in]	svckey_group	is a Service Key for group database access.
[in]	svckeygrouplen	specifies the length in bytes of the svckey_group.
[in]	svckey_pseudo	is a Service Key for pseudonym database access.
[in]	svckeypseudolen	specifies the length in bytes of the svckey_pseudo.

Returns: When the requested_id may replace the current_id then true is returned, otherwise false.