## Authorizations and Authentication Authorizations and Authentication — Obtain authorizations through authentication. |

## Synopsis

                        PolKitGrant;
    void                (*PolKitGrantType)                  (PolKitGrant *polkit_grant,
                                                             PolKitResult grant_type,
                                                             void *user_data);
    char *              (*PolKitGrantSelectAdminUser)       (PolKitGrant *polkit_grant,
                                                             char **admin_users,
                                                             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,
                                                             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);
    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 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.

## Details

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

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

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

`polkit_grant` : | the grant object
`admin_users` : | a NULL-terminated array of users that can be used for authentication for admin grants.
`user_data` : | user data pointed as passed into `polkit_grant_set_functions()`
Returns : | the chosen user; must be allocated with malloc(3) and will be freed by the PolKitGrant class.

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

This function is in `libpolkit-grant`.

Returns : | the new object or NULL if the authorization backend doesn't support obtaining authorizations through authentication.

### polkit_grant_ref ()

    PolKitGrant *       polkit_grant_ref                    (PolKitGrant *polkit_grant);

Increase reference count.

This function is in `libpolkit-grant`.

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

This function is in `libpolkit-grant`.

`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,
                                                             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` : | the object
`func_add_io_watch` : | Callback function
`func_add_child_watch` : | Callback function
`func_remove_watch` : | Callback function
`func_type` : | Callback function
`func_select_admin_user` : | 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.

This function is in `libpolkit-grant`.

`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

This function is in `libpolkit-grant`.

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

This function is in `libpolkit-grant`.

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

This function is in `libpolkit-grant`.

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