docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml


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

<?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&lt;String,String&gt;  details,
                      IN  String               cookie,
                      IN  Array&lt;<link linkend="eggdbus-struct-Identity">Identity</link>&gt;      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&lt;String,String&gt;  details,
                     IN  String               cookie,
                     IN  Array&lt;<link linkend="eggdbus-struct-Identity">Identity</link>&gt;      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.AuthenticationAgentResponse">AuthenticationAgentResponse()</link>
        method on the <link
        linkend="eggdbus-interface-org.freedesktop.PolicyKit1.Authority">org.freedesktop.PolicyKit1.Authority</link>
        interface of the PolicyKit daemon before returning.
      </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&lt;String,String&gt; <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. These strings are translated into the locale passed when registering the authentication agent using <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent()</link>.
Keys starting with <literal>polkit.</literal> are reserved for internal use and should never be displayed in the UI.
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&lt;<link linkend="eggdbus-struct-Identity">Identity</link>&gt; <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>