Core API Reference - Authorization Database
Desktop Apps Training - Policy Kit

Authorization Database

Authorization Database — Reading from and writing to the database storing authorizations

 

Synopsis



PolKitAuthorizationDB;
enum PolKitAuthorizationDBCapability;
PolKitAuthorizationDBCapability polkit_authorization_db_get_capabilities
(void);
PolKitAuthorizationDB* polkit_authorization_db_ref (PolKitAuthorizationDB *authdb);
void polkit_authorization_db_unref (PolKitAuthorizationDB *authdb);
void polkit_authorization_db_debug (PolKitAuthorizationDB *authdb);
polkit_bool_t polkit_authorization_db_validate (PolKitAuthorizationDB *authdb);
polkit_bool_t polkit_authorization_db_is_session_authorized
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitSession *session,
polkit_bool_t *out_is_authorized,
polkit_bool_t *out_is_negative_authorized,
PolKitError **error);
polkit_bool_t polkit_authorization_db_is_caller_authorized
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitCaller *caller,
polkit_bool_t revoke_if_one_shot,
polkit_bool_t *out_is_authorized,
polkit_bool_t *out_is_negative_authorized,
PolKitError **error);
polkit_bool_t (*PolKitAuthorizationDBForeach) (PolKitAuthorizationDB *authdb,
PolKitAuthorization *auth,
void *user_data);
polkit_bool_t polkit_authorization_db_foreach (PolKitAuthorizationDB *authdb,
PolKitAuthorizationDBForeach cb,
void *user_data,
PolKitError **error);
polkit_bool_t polkit_authorization_db_foreach_for_uid
(PolKitAuthorizationDB *authdb,
uid_t uid,
PolKitAuthorizationDBForeach cb,
void *user_data,
PolKitError **error);
polkit_bool_t polkit_authorization_db_foreach_for_action
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitAuthorizationDBForeach cb,
void *user_data,
PolKitError **error);
polkit_bool_t polkit_authorization_db_foreach_for_action_for_uid
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
uid_t uid,
PolKitAuthorizationDBForeach cb,
void *user_data,
PolKitError **error);
polkit_bool_t polkit_authorization_db_add_entry_process_one_shot
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitCaller *caller,
uid_t user_authenticated_as);
polkit_bool_t polkit_authorization_db_add_entry_process
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitCaller *caller,
uid_t user_authenticated_as);
polkit_bool_t polkit_authorization_db_add_entry_session
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitCaller *caller,
uid_t user_authenticated_as);
polkit_bool_t polkit_authorization_db_add_entry_always
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitCaller *caller,
uid_t user_authenticated_as);
polkit_bool_t polkit_authorization_db_grant_to_uid
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
uid_t uid,
PolKitAuthorizationConstraint **constraints,
PolKitError **error);
polkit_bool_t polkit_authorization_db_grant_negative_to_uid
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
uid_t uid,
PolKitAuthorizationConstraint **constraints,
PolKitError **error);
polkit_bool_t polkit_authorization_db_revoke_entry
(PolKitAuthorizationDB *authdb,
PolKitAuthorization *auth,
PolKitError **error);
polkit_bool_t polkit_authorization_db_is_uid_blocked_by_self
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
uid_t uid,
PolKitError **error);

Description

This class presents an abstraction of the authorization database as well as methods for reading and writing to it.

The reading parts are in libpolkit and the writing parts are in libpolkit-grant.

 

Details

PolKitAuthorizationDB

typedef struct {
} PolKitAuthorizationDB;

Objects of this class are used to represent the authorization database.

 

Since 0.7


enum PolKitAuthorizationDBCapability

typedef enum
{
POLKIT_AUTHORIZATION_DB_CAPABILITY_CAN_OBTAIN = 1 << 0
} PolKitAuthorizationDBCapability;

Capabilities of the authorization database backend.

 

POLKIT_AUTHORIZATION_DB_CAPABILITY_CAN_OBTAIN

Users can obtain authorizations through authentication

Since 0.7


polkit_authorization_db_get_capabilities ()

PolKitAuthorizationDBCapability polkit_authorization_db_get_capabilities
(void);

Determine what capabilities the authorization backend has.

 

Returns :

Flags from the PolKitAuthorizationDBCapability enumeration

Since 0.7


polkit_authorization_db_ref ()

PolKitAuthorizationDB* polkit_authorization_db_ref      (PolKitAuthorizationDB *authdb);

Increase reference count.

 

authdb :

the object

Returns :

the object

Since 0.7


polkit_authorization_db_unref ()

void                polkit_authorization_db_unref       (PolKitAuthorizationDB *authdb);

Decreases the reference count of the object. If it becomes zero, the object is freed. Before freeing, reference counts on embedded objects are decresed by one.

 

authdb :

the object

Since 0.7


polkit_authorization_db_debug ()

void                polkit_authorization_db_debug       (PolKitAuthorizationDB *authdb);

Print debug details

 

authdb :

the object

Since 0.7


polkit_authorization_db_validate ()

polkit_bool_t       polkit_authorization_db_validate    (PolKitAuthorizationDB *authdb);

Validate the object

 

authdb :

the object

Returns :

TRUE iff the object is valid.

Since 0.7


polkit_authorization_db_is_session_authorized ()

polkit_bool_t       polkit_authorization_db_is_session_authorized
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitSession *session,
polkit_bool_t *out_is_authorized,
polkit_bool_t *out_is_negative_authorized,
PolKitError **error);

Looks in the authorization database and determine if processes from the given session are authorized to do the given specific action. If there is an authorization record that matches the session, out_is_authorized will be set to TRUE. If there is a negative authorization record matching the session out_is_negative_authorized will be set to TRUE.

 

authdb :

the authorization database

action :

the action to check for

session :

the session to check for

out_is_authorized :

return location

out_is_negative_authorized :

return location

error :

return location for error

Returns :

TRUE if the look up was performed; FALSE if the caller of this function lacks privileges to ask this question (e.g. asking about a user that is not himself) or OOM (and error will be set)

Since 0.7


polkit_authorization_db_is_caller_authorized ()

polkit_bool_t       polkit_authorization_db_is_caller_authorized
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitCaller *caller,
polkit_bool_t revoke_if_one_shot,
polkit_bool_t *out_is_authorized,
polkit_bool_t *out_is_negative_authorized,
PolKitError **error);

Looks in the authorization database if the given caller is authorized to do the given action. If there is an authorization record that matches the caller, out_is_authorized will be set to TRUE. If there is a negative authorization record matching the caller out_is_negative_authorized will be set to TRUE.

 

authdb :

the authorization database

action :

the action to check for

caller :

the caller to check for

revoke_if_one_shot :

Whether to revoke one-shot authorizations. See discussion in polkit_context_is_caller_authorized() for details.

out_is_authorized :

return location

out_is_negative_authorized :

return location

error :

return location for error

Returns :

TRUE if the look up was performed; FALSE if the caller of this function lacks privileges to ask this question (e.g. asking about a user that is not himself) or if OOM (and error will be set)

Since 0.7


PolKitAuthorizationDBForeach ()

polkit_bool_t       (*PolKitAuthorizationDBForeach)     (PolKitAuthorizationDB *authdb,
PolKitAuthorization *auth,
void *user_data);

Type of callback function for iterating over authorizations.

 

authdb :

authorization database

auth :

authorization; user shall not unref this object. Unless reffed by the user it will be destroyed when the callback function returns.

user_data :

user data passed

Returns :

pass TRUE to stop iterating

Since 0.7


polkit_authorization_db_foreach ()

polkit_bool_t       polkit_authorization_db_foreach     (PolKitAuthorizationDB *authdb,
PolKitAuthorizationDBForeach cb,
void *user_data,
PolKitError **error);

Iterate over all entries in the authorization database.

Note that unless the calling process has the authorization org.freedesktop.policykit.read this function may return an error.

 

authdb :

authorization database

cb :

callback

user_data :

user data to pass to callback

error :

return location for error

Returns :

TRUE if the callback returned TRUE to stop iterating. If FALSE, either error may be set or the callback returns FALSE on every invocation.

Since 0.7


polkit_authorization_db_foreach_for_uid ()

polkit_bool_t       polkit_authorization_db_foreach_for_uid
(PolKitAuthorizationDB *authdb,
uid_t uid,
PolKitAuthorizationDBForeach cb,
void *user_data,
PolKitError **error);

Iterate over all entries in the authorization database for a given user.

Note that if the calling process asks for authorizations for a different uid than itself and it lacks the authorization org.freedesktop.policykit.read this function may return an error.

 

authdb :

authorization database

uid :

user to get authorizations for

cb :

callback

user_data :

user data to pass to callback

error :

return location for error

Returns :

TRUE if the callback returned TRUE to stop iterating. If FALSE, either error may be set or the callback returns FALSE on every invocation.

Since 0.7


polkit_authorization_db_foreach_for_action ()

polkit_bool_t       polkit_authorization_db_foreach_for_action
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitAuthorizationDBForeach cb,
void *user_data,
PolKitError **error);

Iterate over all entries in the authorization database for a given action.

Note that unless the calling process has the authorization org.freedesktop.policykit.read this function may return an error.

 

authdb :

authorization database

action :

action to get authorizations for

cb :

callback

user_data :

user data to pass to callback

error :

return location for error

Returns :

TRUE if the callback returned TRUE to stop iterating. If FALSE, either error may be set or the callback returns FALSE on every invocation.

Since 0.7


polkit_authorization_db_foreach_for_action_for_uid ()

polkit_bool_t       polkit_authorization_db_foreach_for_action_for_uid
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
uid_t uid,
PolKitAuthorizationDBForeach cb,
void *user_data,
PolKitError **error);

Iterate over all entries in the authorization database for a given action and user.

Note that if the calling process asks for authorizations for a different uid than itself and it lacks the authorization org.freedesktop.policykit.read this function may return an error.

 

authdb :

authorization database

action :

action to get authorizations for

uid :

user to get authorizations for

cb :

callback

user_data :

user data to pass to callback

error :

return location for error

Returns :

TRUE if the callback returned TRUE to stop iterating. If FALSE, either error may be set or the callback returns FALSE on every invocation.

Since 0.7


polkit_authorization_db_add_entry_process_one_shot ()

polkit_bool_t       polkit_authorization_db_add_entry_process_one_shot
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitCaller *caller,
uid_t user_authenticated_as);

Write an entry to the authorization database to indicate that the given caller is authorized for the given action a single time.

Note that this function should only be used by libpolkit-grant or other sufficiently privileged processes that deals with managing authorizations. It should never be used by mechanisms or applications. The caller must have egid=polkituser and umask set so creating files with mode 0460 will work.

This function is in libpolkit-grant.

 

authdb :

the authorization database

action :

the action

caller :

the caller

user_authenticated_as :

the user that was authenticated

Returns :

TRUE if an entry was written to the authorization database, FALSE if the caller of this function is not sufficiently privileged.

Since 0.7


polkit_authorization_db_add_entry_process ()

polkit_bool_t       polkit_authorization_db_add_entry_process
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitCaller *caller,
uid_t user_authenticated_as);

Write an entry to the authorization database to indicate that the given caller is authorized for the given action.

Note that this function should only be used by libpolkit-grant or other sufficiently privileged processes that deals with managing authorizations. It should never be used by mechanisms or applications. The caller must have egid=polkituser and umask set so creating files with mode 0460 will work.

This function is in libpolkit-grant.

 

authdb :

the authorization database

action :

the action

caller :

the caller

user_authenticated_as :

the user that was authenticated

Returns :

TRUE if an entry was written to the authorization database, FALSE if the caller of this function is not sufficiently privileged.

Since 0.7


polkit_authorization_db_add_entry_session ()

polkit_bool_t       polkit_authorization_db_add_entry_session
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitCaller *caller,
uid_t user_authenticated_as);

Write an entry to the authorization database to indicate that the session for the given caller is authorized for the given action for the remainer of the session.

Note that this function should only be used by libpolkit-grant or other sufficiently privileged processes that deals with managing authorizations. It should never be used by mechanisms or applications. The caller must have egid=polkituser and umask set so creating files with mode 0460 will work.

This function is in libpolkit-grant.

 

authdb :

the authorization database

action :

the action

caller :

the caller

user_authenticated_as :

the user that was authenticated

Returns :

TRUE if an entry was written to the authorization database, FALSE if the caller of this function is not sufficiently privileged.

Since 0.7


polkit_authorization_db_add_entry_always ()

polkit_bool_t       polkit_authorization_db_add_entry_always
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
PolKitCaller *caller,
uid_t user_authenticated_as);

Write an entry to the authorization database to indicate that the given user is authorized for the given action.

Note that this function should only be used by libpolkit-grant or other sufficiently privileged processes that deals with managing authorizations. It should never be used by mechanisms or applications. The caller must have egid=polkituser and umask set so creating files with mode 0460 will work.

This function is in libpolkit-grant.

 

authdb :

the authorization database

action :

the action

caller :

the caller

user_authenticated_as :

the user that was authenticated

Returns :

TRUE if an entry was written to the authorization database, FALSE if the caller of this function is not sufficiently privileged.

Since 0.7


polkit_authorization_db_grant_to_uid ()

polkit_bool_t       polkit_authorization_db_grant_to_uid
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
uid_t uid,
PolKitAuthorizationConstraint **constraints,
PolKitError **error);

Grants an authorization to a user for a specific action. This requires the org.freedesktop.policykit.grant authorization.

This function is in libpolkit-grant.

 

authdb :

authorization database

action :

action

uid :

uid to grant to

constraints :

Either NULL or a NULL terminated list of constraint to put on the authorization

error :

return location for error

Returns :

TRUE if the authorization was granted, FALSE otherwise and error will be set

Since 0.7


polkit_authorization_db_grant_negative_to_uid ()

polkit_bool_t       polkit_authorization_db_grant_negative_to_uid
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
uid_t uid,
PolKitAuthorizationConstraint **constraints,
PolKitError **error);

Grants a negative authorization to a user for a specific action. If uid differs from the calling user, the org.freedesktop.policykit.grant authorization is required. In other words, users may "grant" negative authorizations to themselves.

A negative authorization is normally used to block users that would normally be authorized from an implicit authorization.

This function is in libpolkit-grant.

 

authdb :

authorization database

action :

action

uid :

uid to grant to

constraints :

Either NULL or a NULL terminated list of constraint to put on the authorization

error :

return location for error

Returns :

TRUE if the authorization was granted, FALSE otherwise and error will be set

Since 0.7


polkit_authorization_db_revoke_entry ()

polkit_bool_t       polkit_authorization_db_revoke_entry
(PolKitAuthorizationDB *authdb,
PolKitAuthorization *auth,
PolKitError **error);

Removes an authorization from the authorization database. This uses a privileged helper /usr/libexec/polkit-revoke-helper.

 

authdb :

the authorization database

auth :

the authorization to revoke

error :

return location for error

Returns :

TRUE if the authorization was revoked, FALSE otherwise and error is set

Since 0.7


polkit_authorization_db_is_uid_blocked_by_self ()

polkit_bool_t       polkit_authorization_db_is_uid_blocked_by_self
(PolKitAuthorizationDB *authdb,
PolKitAction *action,
uid_t uid,
PolKitError **error);

Determine whether there exists negative authorizations for the particular uid on the given action and whether those negative authorization are "granted" by the uid itself.

If uid is different from getuid(), e.g. if the calling process asks for auths of another user this function will set an error if the calling user is not authorized for org.freedesktop.policykit.read.

 

authdb :

the authorization database

action :

the action to check for

uid :

the user to check for

error :

return location for error

Returns :

Result of computation described above; if error is set will return FALSE.

Since 0.7