1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2 //EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="eggdbus-interface-org.freedesktop.PolicyKit1.AuthenticationAgent">
<refmeta>
<refentrytitle role="top_of_page">org.freedesktop.PolicyKit1.AuthenticationAgent Interface</refentrytitle>
</refmeta>
<refnamediv>
<refname>org.freedesktop.PolicyKit1.AuthenticationAgent Interface</refname>
<refpurpose>Authentication Agent Interface</refpurpose>
</refnamediv>
<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Methods</title>
<synopsis>
<link linkend="eggdbus-method-org.freedesktop.PolicyKit1.AuthenticationAgent.BeginAuthentication">BeginAuthentication</link> (IN String action_id,
IN String message,
IN String icon_name,
IN Dict<String,String> details,
IN String cookie,
IN Array<<link linkend="eggdbus-struct-Identity">Identity</link>> identities)
<link linkend="eggdbus-method-org.freedesktop.PolicyKit1.AuthenticationAgent.CancelAuthentication">CancelAuthentication</link> (IN String cookie)
</synopsis>
</refsynopsisdiv>
<refsect1 role="desc" id="eggdbus-if-description-org.freedesktop.PolicyKit1.AuthenticationAgent">
<title role="desc.title">Description</title>
<para>
<para>This D-Bus interface is used for communication between the system-wide PolicyKit daemon and one or more authentication agents each running in a user session.</para><para>An authentication agent must implement this interface and register (passing the object path of the object implementing the interface) using the <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent()</link> and <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.UnregisterAuthenticationAgent">UnregisterAuthenticationAgent()</link> methods on the <link linkend="eggdbus-interface-org.freedesktop.PolicyKit1.Authority">org.freedesktop.PolicyKit1.Authority</link> interface of the PolicyKit daemon.</para>
</para>
</refsect1>
<refsect1 role="details" id="eggdbus-if-method-details-org.freedesktop.PolicyKit1.AuthenticationAgent">
<title role="details.title">Method Details</title>
<refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.AuthenticationAgent.BeginAuthentication">
<title>BeginAuthentication ()</title>
<programlisting>
BeginAuthentication (IN String action_id,
IN String message,
IN String icon_name,
IN Dict<String,String> details,
IN String cookie,
IN Array<<link linkend="eggdbus-struct-Identity">Identity</link>> identities)
</programlisting>
<para>
<para>
Called by the PolicyKit daemon when the authentication agent
needs the user to authenticate as one of the identities in
<parameter>identities</parameter> for the action with the
identifier <parameter>action_id</parameter>.</para><para>Upon
succesful authentication, the authentication agent must invoke
the <link
linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2">AuthenticationAgentResponse2()</link>
method on the <link
linkend="eggdbus-interface-org.freedesktop.PolicyKit1.Authority">org.freedesktop.PolicyKit1.Authority</link>
interface of the PolicyKit daemon before returning. This is normally
achieved via the <link linkend="PolkitAgentSession">PolkitAgentSession</link>
API, which invokes a private setuid helper process to verify the
authentication.
</para>
<para>
The authentication agent should not return until after authentication is complete.
If the user dismisses the authentication dialog, the authentication agent should return the <link linkend="eggdbus-constant-Error.org.freedesktop.PolicyKit1.Error.Cancelled">org.freedesktop.PolicyKit1.Error.Cancelled</link> error.
</para>
</para>
<variablelist role="params">
<varlistentry>
<term><literal>IN String <parameter>action_id</parameter></literal>:</term>
<listitem>
<para>
The identifier for the action that the user is authentication for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>IN String <parameter>message</parameter></literal>:</term>
<listitem>
<para>
The message to display to the user. This is translated into the locale passed when registering the authentication agent using <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent()</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>IN String <parameter>icon_name</parameter></literal>:</term>
<listitem>
<para>
The themed icon describing the action or the empty string if no icon is set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>IN Dict<String,String> <parameter>details</parameter></literal>:</term>
<listitem>
<para>
Details about the authentication request. This is a dictionary
of key/value pairs where both key and value are strings.
Known key/value-pairs include
<literal>polkit.caller-pid</literal> (the process id of the
mechanism making the authorization check) and
<literal>polkit.subject-pid</literal> (the process id of the
subject the check is for).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>IN String <parameter>cookie</parameter></literal>:</term>
<listitem>
<para>
A cookie identifying the authentication request.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>IN Array<<link linkend="eggdbus-struct-Identity">Identity</link>> <parameter>identities</parameter></literal>:</term>
<listitem>
<para>
An array of <link linkend="eggdbus-struct-Identity">Identity</link> structs that the user can use for authentication.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.AuthenticationAgent.CancelAuthentication">
<title>CancelAuthentication ()</title>
<programlisting>
CancelAuthentication (IN String cookie)
</programlisting>
<para>
Called by the PolicyKit daemon if the authentication agent needs to cancel an authentication dialog.
</para>
<variablelist role="params">
<varlistentry>
<term><literal>IN String <parameter>cookie</parameter></literal>:</term>
<listitem>
<para>
The cookie identifying the authentication request.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
</refentry>
|
