Core API Reference - Authorizations and Authentication

PolKitGrant

typedef struct _PolKitGrant PolKitGrant;

Objects of this class are used to obtain authorizations for a user that is able to successfully authenticate. It is only useful for people writing user interfaces that interfaces with the end user.

All of these functions are in the libpolkit-grant library.

PolKitGrantType ()

void                (*PolKitGrantType)                  (PolKitGrant *polkit_grant,
                                                         PolKitResult grant_type,
                                                         void *user_data);

Type for callback function that describes to what extent the privilege can be obtained; e.g. whether the user can keep it (e.g. forever, for the session or not keep it at all).

See also PolKitGrantOverrideGrantType for discussion on the type of user interfaces one should put up depending on the value of grant_type.

PolKitGrantSelectAdminUser ()

char*               (*PolKitGrantSelectAdminUser)       (PolKitGrant *polkit_grant,
                                                         char **admin_users,
                                                         void *user_data);

Type for callback function that describes the possible users that can be chosen for authentication when administrator privileges are required.

PolKitGrantConversationPromptEchoOff ()

char*               (*PolKitGrantConversationPromptEchoOff)
                                                        (PolKitGrant *polkit_grant,
                                                         const char *prompt,
                                                         void *user_data);

Type for callback function that is invoked when the authentication layer needs to ask the user a secret and the UI should NOT echo what the user types on the screen.

PolKitGrantConversationPromptEchoOn ()

char*               (*PolKitGrantConversationPromptEchoOn)
                                                        (PolKitGrant *polkit_grant,
                                                         const char *prompt,
                                                         void *user_data);

Type for callback function that is invoked when the authentication layer needs to ask the user a secret and the UI should echo what the user types on the screen.

PolKitGrantConversationErrorMessage ()

void                (*PolKitGrantConversationErrorMessage)
                                                        (PolKitGrant *polkit_grant,
                                                         const char *error_message,
                                                         void *user_data);

Type for callback function that is invoked when the authentication layer produces an error message that should be displayed in the UI.

PolKitGrantConversationTextInfo ()

void                (*PolKitGrantConversationTextInfo)  (PolKitGrant *polkit_grant,
                                                         const char *text_info,
                                                         void *user_data);

Type for callback function that is invoked when the authentication layer produces an informational message that should be displayed in the UI.

PolKitGrantOverrideGrantType ()

PolKitResult        (*PolKitGrantOverrideGrantType)     (PolKitGrant *polkit_grant,
                                                         PolKitResult grant_type,
                                                         void *user_data);

Type for callback function that enables the UI to request a lesser privilege than is obtainable. This callback is invoked when the user have successfully authenticated but before the privilege is granted.

Basically, this callback enables a program to provide an user interface like this:

+------------------------------------------------------------+
| You need to authenticate to access the volume 'Frobnicator |
| Adventures Vol 2'                                          |
|                                                            |
| Password: [_________________]                              |
|                                                            |
[ [x] Remember this decision                                 |
|   [ ] for this session                                     |
|   [*] for this and future sessions                         |
|                                                            |
|                                    [Cancel] [Authenticate] |
+------------------------------------------------------------+

This dialog assumes that grant_type passed was POLKIT_RESULT_ONLY_VIA_SELF_AUTH_KEEP_ALWAYS. By ticking the check boxes in the dialog, the user can override this to either POLKIT_RESULT_ONLY_VIA_SELF_AUTH_KEEP_SESSION or POLKIT_RESULT_ONLY_VIA_SELF_AUTH. Thus, the user can voluntarily choose to obtain a lesser privilege.

Another example, would be that the grant_type passed was POLKIT_RESULT_ONLY_VIA_SELF_AUTH_KEEP_SESSION. Then the dialog should look like this:

+------------------------------------------------------------+
| You need to authenticate to access the volume 'Frobnicator |
| Adventures Vol 2'                                          |
|                                                            |
| Password: [_________________]                              |
|                                                            |
[ [x] Remember this decision for the rest of the session     |
|                                                            |
|                                    [Cancel] [Authenticate] |
+------------------------------------------------------------+

Finally, if the grant_type value passed is e.g. POLKIT_RESULT_ONLY_VIA_SELF_AUTH, there are no options to click.:

+------------------------------------------------------------+
| You need to authenticate to access the volume 'Frobnicator |
| Adventures Vol 2'                                          |
|                                                            |
| Password: [_________________]                              |
|                                                            |
|                                    [Cancel] [Authenticate] |
+------------------------------------------------------------+

Of course, these examples also applies to POLKIT_RESULT_ONLY_VIA_ADMIN_AUTH and friends.

PolKitGrantDone ()

void                (*PolKitGrantDone)                  (PolKitGrant *polkit_grant,
                                                         polkit_bool_t gained_privilege,
                                                         polkit_bool_t invalid_data,
                                                         void *user_data);

This function is called when the granting process ends; either if successful or if it was canceled using e.g. polkit_grant_cancel_auth().

PolKitGrantAddChildWatch ()

int                 (*PolKitGrantAddChildWatch)         (PolKitGrant *polkit_grant,
                                                         pid_t pid);

Type for function supplied by the application to integrate a watch on a child process into the applications main loop. The application must call polkit_grant_child_func() when the child dies

For glib mainloop, the function will typically look like this:

static void
child_watch_func (GPid pid,
                  gint status,
                  gpointer user_data)
{
        PolKitGrant *polkit_grant = user_data;
        polkit_grant_child_func (polkit_grant, pid, WEXITSTATUS (status));
}

static int 
add_child_watch (PolKitGrant *polkit_grant, pid_t pid)
{
        return g_child_watch_add (pid, child_watch_func, polkit_grant);
}

PolKitGrantAddIOWatch ()

int                 (*PolKitGrantAddIOWatch)            (PolKitGrant *polkit_grant,
                                                         int fd);

Type for function supplied by the application to integrate a watch on a file descriptor into the applications main loop. The application must call polkit_grant_io_func() when there is data to read from the file descriptor.

For glib mainloop, the function will typically look like this:

static gboolean
io_watch_have_data (GIOChannel *channel, GIOCondition condition, gpointer user_data)
{
        int fd;
        PolKitGrant *polkit_grant = user_data;
        fd = g_io_channel_unix_get_fd (channel);
        polkit_grant_io_func (polkit_grant, fd);
        return TRUE;
}

static int 
add_io_watch (PolKitGrant *polkit_grant, int fd)
{
        guint id = 0;
        GIOChannel *channel;
        channel = g_io_channel_unix_new (fd);
        if (channel == NULL)
                goto out;
        id = g_io_add_watch (channel, G_IO_IN, io_watch_have_data, polkit_grant);
        if (id == 0) {
                g_io_channel_unref (channel);
                goto out;
        }
        g_io_channel_unref (channel);
out:
        return id;
}

PolKitGrantRemoveWatch ()

void                (*PolKitGrantRemoveWatch)           (PolKitGrant *polkit_grant,
                                                         int watch_id);

Type for function supplied by the application to remove a watch set up via the supplied function of type PolKitGrantAddIOWatch or type PolKitGrantAddChildWatch.

For glib mainloop, the function will typically look like this:

static void 
remove_watch (PolKitGrant *polkit_auth, int watch_id)
{
        g_source_remove (watch_id);
}

polkit_grant_new ()

PolKitGrant*        polkit_grant_new                    (void);

Creates a PolKitGrant object.

This function is in libpolkit-grant.

polkit_grant_ref ()

PolKitGrant*        polkit_grant_ref                    (PolKitGrant *polkit_grant);

Increase reference count.

This function is in libpolkit-grant.

polkit_grant_unref ()

void                polkit_grant_unref                  (PolKitGrant *polkit_grant);

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.

This function is in libpolkit-grant.

polkit_grant_set_functions ()

void                polkit_grant_set_functions          (PolKitGrant *polkit_grant,
                                                         PolKitGrantAddIOWatch func_add_io_watch,
                                                         PolKitGrantAddChildWatch func_add_child_watch,
                                                         PolKitGrantRemoveWatch func_remove_watch,
                                                         PolKitGrantType func_type,
                                                         PolKitGrantSelectAdminUser func_select_admin_user,
                                                         PolKitGrantConversationPromptEchoOff func_prompt_echo_off,
                                                         PolKitGrantConversationPromptEchoOn func_prompt_echo_on,
                                                         PolKitGrantConversationErrorMessage func_error_message,
                                                         PolKitGrantConversationTextInfo func_text_info,
                                                         PolKitGrantOverrideGrantType func_override_grant_type,
                                                         PolKitGrantDone func_done,
                                                         void *user_data);

Set callback functions used for authentication.

This function is in libpolkit-grant.

polkit_grant_initiate_auth ()

polkit_bool_t       polkit_grant_initiate_auth          (PolKitGrant *polkit_grant,
                                                         PolKitAction *action,
                                                         PolKitCaller *caller);

Initiate authentication to obtain the privilege for the given caller to perform the specified action. The caller of this method must have setup callback functions using the method polkit_grant_set_functions() prior to calling this method.

Implementation-wise, this class uses a secure (e.g. as in that it checks all information and fundamenally don't trust the caller; e.g. the PolKitGrant class) setgid helper that does all the heavy lifting.

The caller of this method must iterate the mainloop context in order for authentication to make progress.

This function is in libpolkit-grant.

polkit_grant_cancel_auth ()

void                polkit_grant_cancel_auth            (PolKitGrant *polkit_grant);

Cancel an authentication in progress

This function is in libpolkit-grant.

polkit_grant_io_func ()

void                polkit_grant_io_func                (PolKitGrant *polkit_grant,
                                                         int fd);

Method that the application must call when there is data to read from a file descriptor registered with the supplied function of type PolKitGrantAddIOWatch.

This function is in libpolkit-grant.

polkit_grant_child_func ()

void                polkit_grant_child_func             (PolKitGrant *polkit_grant,
                                                         pid_t pid,
                                                         int exit_code);

Method that the application must call when a child process registered with the supplied function of type PolKitGrantAddChildWatch terminates.

This function is in libpolkit-grant.