polkit-grant

polkit-grant — Obtain privileges through authentication.

Synopsis




struct              PolKitGrant;
void                (*PolKitGrantType)                  (PolKitGrant *polkit_grant,
                                                         PolKitResult grant_type,
                                                         void *user_data);
char*               (*PolKitGrantConversationPromptEchoOff)
                                                        (PolKitGrant *polkit_grant,
                                                         const char *prompt,
                                                         void *user_data);
char*               (*PolKitGrantConversationPromptEchoOn)
                                                        (PolKitGrant *polkit_grant,
                                                         const char *prompt,
                                                         void *user_data);
void                (*PolKitGrantConversationErrorMessage)
                                                        (PolKitGrant *polkit_grant,
                                                         const char *error_message,
                                                         void *user_data);
void                (*PolKitGrantConversationTextInfo)  (PolKitGrant *polkit_grant,
                                                         const char *text_info,
                                                         void *user_data);
PolKitResult        (*PolKitGrantOverrideGrantType)     (PolKitGrant *polkit_grant,
                                                         PolKitResult grant_type,
                                                         void *user_data);
void                (*PolKitGrantDone)                  (PolKitGrant *polkit_grant,
                                                         polkit_bool_t gained_privilege,
                                                         polkit_bool_t invalid_data,
                                                         void *user_data);
int                 (*PolKitGrantAddChildWatch)         (PolKitGrant *polkit_grant,
                                                         pid_t pid);
int                 (*PolKitGrantAddIOWatch)            (PolKitGrant *polkit_grant,
                                                         int fd);
void                (*PolKitGrantRemoveWatch)           (PolKitGrant *polkit_grant,
                                                         int watch_id);
PolKitGrant*        polkit_grant_new                    (void);
PolKitGrant*        polkit_grant_ref                    (PolKitGrant *polkit_grant);
void                polkit_grant_unref                  (PolKitGrant *polkit_grant);
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,
                                                         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);
polkit_bool_t       polkit_grant_initiate_auth          (PolKitGrant *polkit_grant,
                                                         PolKitAction *action,
                                                         PolKitCaller *caller);
void                polkit_grant_cancel_auth            (PolKitGrant *polkit_grant);
void                polkit_grant_io_func                (PolKitGrant *polkit_grant,
                                                         int fd);
void                polkit_grant_child_func             (PolKitGrant *polkit_grant,
                                                         pid_t pid,
                                                         int exit_code);

Description

These functions are used to obtain privileges for a user that is able to successfully authenticate.

Details

struct PolKitGrant

struct PolKitGrant;

Objects of this class are used to obtain privileges for a user that is able to successfully authenticate.


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.

polkit_grant : the grant object
grant_type : the current type of what privilege to obtain
user_data : user data pointed as passed into polkit_grant_set_functions()

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.

polkit_grant : the grant object
prompt : prompt passed by the authentication layer; do not free this string
user_data : user data pointed as passed into polkit_grant_set_functions()
Returns : the answer obtained from the user; must be allocated with malloc(3) and will be freed by the PolKitGrant class.

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.

polkit_grant : the grant object
prompt : prompt passed by the authentication layer; do not free this string
user_data : user data pointed as passed into polkit_grant_set_functions()
Returns : the answer obtained from the user; must be allocated with malloc(3) and will be freed by the PolKitGrant class.

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.

polkit_grant : the grant object
error_message : error message passed by the authentication layer; do not free this string
user_data : user data pointed as passed into polkit_grant_set_functions()

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.

polkit_grant : the grant object
text_info : information passed by the authentication layer; do not free this string
user_data : user data pointed as passed into polkit_grant_set_functions()

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_ROOT_AUTH and friends.

polkit_grant : the grant object
grant_type : the current type of what privilege to obtain; this is the same value as passed to the callback of type PolKitGrantType.
user_data : user data pointed as passed into polkit_grant_set_functions()
Returns : the desired type of what privilege to obtain; note that it won't work asking for more privileges than what grant_type specifies; the passed value is properly checked in the secure setgid granting helper mentioned in polkit_grant_initiate_auth().

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().

polkit_grant : the grant object
gained_privilege : whether the privilege was obtained
invalid_data : whether the input data was bogus (not including bad passwords)
user_data : user data pointed as passed into polkit_grant_set_functions()

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);
}

polkit_grant : the grant object
pid : the child pid to watch
Returns : 0 if the watch couldn't be set up; otherwise an unique identifier for the watch.

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;
}

polkit_grant : the grant object
fd : the file descriptor to watch
Returns : 0 if the watch couldn't be set up; otherwise an unique identifier for the watch.

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 : the grant object
watch_id : the id obtained from using the supplied function of type PolKitGrantAddIOWatch or PolKitGrantAddChildWatch.

polkit_grant_new ()

PolKitGrant*        polkit_grant_new                    (void);

Creates a PolKitGrant object.

Returns : the new object or NULL on error.

polkit_grant_ref ()

PolKitGrant*        polkit_grant_ref                    (PolKitGrant *polkit_grant);

Increase reference count.

polkit_grant : the object
Returns : the object.

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.

polkit_grant : the object

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,
                                                         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.

polkit_grant : the object
func_add_io_watch : Callback function
func_add_child_watch : Callback function
func_remove_watch : Callback function
func_type : Callback function
func_prompt_echo_off : Callback function
func_prompt_echo_on : Callback function
func_error_message : Callback function
func_text_info : Callback function
func_override_grant_type : Callback function
func_done : Callback function
user_data : User data that will be passed to the callback functions.

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.

polkit_grant : the object
action : Action requested by caller
caller : Caller in question
Returns : TRUE only if authentication have been initiated.

polkit_grant_cancel_auth ()

void                polkit_grant_cancel_auth            (PolKitGrant *polkit_grant);

Cancel an authentication in progress

polkit_grant : the object

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.

polkit_grant : the object
fd : the file descriptor passed to the supplied function of type PolKitGrantAddIOWatch.

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.

polkit_grant : the object
pid : pid of the child
exit_code : exit code of the child