## 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

## 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