Core API Reference - Authorizations and Authentication
Desktop Apps Training - Policy Kit

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