Debian Codegraph @

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

raw
1 <?xml version="1.0"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2 //EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4 <refentry id="eggdbus-interface-org.freedesktop.PolicyKit1.Authority">
5 <refmeta>
6 <refentrytitle role="top_of_page">org.freedesktop.PolicyKit1.Authority Interface</refentrytitle>
7 </refmeta>
8 <refnamediv>
9 <refname>org.freedesktop.PolicyKit1.Authority Interface</refname>
10 <refpurpose>Authority Interface</refpurpose>
11 </refnamediv>
12 <refsynopsisdiv role="synopsis">
13 <title role="synopsis.title">Methods</title>
14 <synopsis>
15 Flags <link linkend="eggdbus-enum-CheckAuthorizationFlags">CheckAuthorizationFlags</link>
16 Enumeration <link linkend="eggdbus-enum-ImplicitAuthorization">ImplicitAuthorization</link>
17 ErrorDomain <link linkend="eggdbus-errordomain-org.freedesktop.PolicyKit1.Error.">org.freedesktop.PolicyKit1.Error.*</link>
18 Flags <link linkend="eggdbus-enum-AuthorityFeatures">AuthorityFeatures</link>
19 Structure <link linkend="eggdbus-struct-Subject">Subject</link>
20 Structure <link linkend="eggdbus-struct-Identity">Identity</link>
21 Structure <link linkend="eggdbus-struct-ActionDescription">ActionDescription</link>
22 Structure <link linkend="eggdbus-struct-AuthorizationResult">AuthorizationResult</link>
23 Structure <link linkend="eggdbus-struct-TemporaryAuthorization">TemporaryAuthorization</link>
24
25 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.EnumerateActions">EnumerateActions</link> (IN String locale,
26 OUT Array&lt;<link linkend="eggdbus-struct-ActionDescription">ActionDescription</link>&gt; action_descriptions)
27 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CheckAuthorization">CheckAuthorization</link> (IN <link linkend="eggdbus-struct-Subject">Subject</link> subject,
28 IN String action_id,
29 IN Dict&lt;String,String&gt; details,
30 IN <link linkend="eggdbus-enum-CheckAuthorizationFlags">CheckAuthorizationFlags</link> flags,
31 IN String cancellation_id,
32 OUT <link linkend="eggdbus-struct-AuthorizationResult">AuthorizationResult</link> result)
33 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CancelCheckAuthorization">CancelCheckAuthorization</link> (IN String cancellation_id)
34 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent</link> (IN <link linkend="eggdbus-struct-Subject">Subject</link> subject,
35 IN String locale,
36 IN String object_path)
37 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgentWithOptions">RegisterAuthenticationAgentWithOptions</link> (IN <link linkend="eggdbus-struct-Subject">Subject</link> subject,
38 IN String locale,
39 IN String object_path,
40 IN Dict&lt;String,Variant&gt; options)
41 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.UnregisterAuthenticationAgent">UnregisterAuthenticationAgent</link> (IN <link linkend="eggdbus-struct-Subject">Subject</link> subject,
42 IN String object_path)
43 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse">AuthenticationAgentResponse</link> (IN String cookie,
44 IN <link linkend="eggdbus-struct-Identity">Identity</link> identity)
45 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2">AuthenticationAgentResponse2</link> (IN uint32 uid, IN String cookie,
46 IN <link linkend="eggdbus-struct-Identity">Identity</link> identity)
47 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse3">AuthenticationAgentResponse3</link> (IN String cookie,
48 IN <link linkend="eggdbus-struct-Identity">Identity</link> identity,
49 IN <link linkend="eggdbus-struct-Subject">Subject</link> subject)
50 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.EnumerateTemporaryAuthorizations">EnumerateTemporaryAuthorizations</link> (IN <link linkend="eggdbus-struct-Subject">Subject</link> subject,
51 OUT Array&lt;<link linkend="eggdbus-struct-TemporaryAuthorization">TemporaryAuthorization</link>&gt; temporary_authorizations)
52 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RevokeTemporaryAuthorizations">RevokeTemporaryAuthorizations</link> (IN <link linkend="eggdbus-struct-Subject">Subject</link> subject)
53 <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RevokeTemporaryAuthorizationById">RevokeTemporaryAuthorizationById</link> (IN String id)
54 </synopsis>
55 </refsynopsisdiv>
56 <refsect1 role="signal_proto" id="eggdbus-if-signals-org.freedesktop.PolicyKit1.Authority">
57 <title role="signal_proto.title">Signals</title>
58 <synopsis>
59 <link linkend="eggdbus-signal-org.freedesktop.PolicyKit1.Authority::Changed">Changed</link> ()
60 </synopsis>
61 </refsect1>
62 <refsect1 role="properties" id="eggdbus-if-properties-org.freedesktop.PolicyKit1.Authority">
63 <title role="properties.title">Properties</title>
64 <synopsis>
65 <link linkend="eggdbus-property-org.freedesktop.PolicyKit1.Authority:BackendName">BackendName</link> readable String
66 <link linkend="eggdbus-property-org.freedesktop.PolicyKit1.Authority:BackendVersion">BackendVersion</link> readable String
67 <link linkend="eggdbus-property-org.freedesktop.PolicyKit1.Authority:BackendFeatures">BackendFeatures</link> readable <link linkend="eggdbus-enum-AuthorityFeatures">AuthorityFeatures</link>
68 </synopsis>
69 </refsect1>
70 <refsect1 role="desc" id="eggdbus-if-description-org.freedesktop.PolicyKit1.Authority">
71 <title role="desc.title">Description</title>
72 <para>
73 This D-Bus interface is implemented by the <literal>/org/freedesktop/PolicyKit1/Authority</literal> object on the well-known name <literal>org.freedesktop.PolicyKit1</literal> on the system message bus.
74 </para>
75 </refsect1>
76 <refsect1 role="desc" id="eggdbus-if-enumerations-org.freedesktop.PolicyKit1.Authority">
77 <title role="desc.title">Enumerations</title>
78 <refsect2 role="enum" id="eggdbus-enum-CheckAuthorizationFlags">
79 <title>The CheckAuthorizationFlags Flags</title>
80 <para>
81 <programlisting>
82 {
83 None = 0x00000000,
84 AllowUserInteraction = 0x00000001,
85 AlwaysCheck = 0x00000002
86 }
87 </programlisting>
88 <para>
89 Flags used in the <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CheckAuthorization">CheckAuthorization()</link> method.
90 </para>
91 <variablelist role="constant">
92 <varlistentry id="eggdbus-constant-CheckAuthorizationFlags.None" role="constant">
93 <term><literal>None</literal></term>
94 <listitem>
95 <para>
96 No flags set.
97 </para>
98 </listitem>
99 </varlistentry>
100 <varlistentry id="eggdbus-constant-CheckAuthorizationFlags.AllowUserInteraction" role="constant">
101 <term><literal>AllowUserInteraction</literal></term>
102 <listitem>
103 <para>
104 If the <link linkend="eggdbus-struct-Subject">Subject</link> can obtain the authorization through authentication, and an authentication agent is available, then attempt to do so. Note, this means that the <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CheckAuthorization">CheckAuthorization()</link> method will block while the user is being asked to authenticate.
105 </para>
106 </listitem>
107 </varlistentry>
108 <varlistentry id="eggdbus-constant-CheckAuthorizationFlags.AlwaysCheck" role="constant">
109 <term><literal>AlwaysCheck</literal></term>
110 <listitem>
111 <para>
112 Check access against policy even if the <link linkend="eggdbus-struct-Subject">Subject</link> is the root user.
113 </para>
114 </listitem>
115 </varlistentry>
116 </variablelist>
117 </para>
118 </refsect2>
119 <refsect2 role="enum" id="eggdbus-enum-ImplicitAuthorization">
120 <title>The ImplicitAuthorization Enumeration</title>
121 <para>
122 <programlisting>
123 {
124 NotAuthorized = 0,
125 AuthenticationRequired = 1,
126 AdministratorAuthenticationRequired = 2,
127 AuthenticationRequiredRetained = 3,
128 AdministratorAuthenticationRequiredRetained = 4,
129 Authorized = 5
130 }
131 </programlisting>
132 <para>
133 An enumeration for granting implicit authorizations.
134 </para>
135 <variablelist role="constant">
136 <varlistentry id="eggdbus-constant-ImplicitAuthorization.NotAuthorized" role="constant">
137 <term><literal>NotAuthorized</literal></term>
138 <listitem>
139 <para>
140 The <link linkend="eggdbus-struct-Subject">Subject</link> is not authorized.
141 </para>
142 </listitem>
143 </varlistentry>
144 <varlistentry id="eggdbus-constant-ImplicitAuthorization.AuthenticationRequired" role="constant">
145 <term><literal>AuthenticationRequired</literal></term>
146 <listitem>
147 <para>
148 Authentication is required.
149 </para>
150 </listitem>
151 </varlistentry>
152 <varlistentry id="eggdbus-constant-ImplicitAuthorization.AdministratorAuthenticationRequired" role="constant">
153 <term><literal>AdministratorAuthenticationRequired</literal></term>
154 <listitem>
155 <para>
156 Authentication as an administrator is required.
157 </para>
158 </listitem>
159 </varlistentry>
160 <varlistentry id="eggdbus-constant-ImplicitAuthorization.AuthenticationRequiredRetained" role="constant">
161 <term><literal>AuthenticationRequiredRetained</literal></term>
162 <listitem>
163 <para>
164 Authentication is required. If the authorization is obtained, it is retained.
165 </para>
166 </listitem>
167 </varlistentry>
168 <varlistentry id="eggdbus-constant-ImplicitAuthorization.AdministratorAuthenticationRequiredRetained" role="constant">
169 <term><literal>AdministratorAuthenticationRequiredRetained</literal></term>
170 <listitem>
171 <para>
172 Authentication as an administrator is required. If the authorization is obtained, it is retained.
173 </para>
174 </listitem>
175 </varlistentry>
176 <varlistentry id="eggdbus-constant-ImplicitAuthorization.Authorized" role="constant">
177 <term><literal>Authorized</literal></term>
178 <listitem>
179 <para>
180 The subject is authorized.
181 </para>
182 </listitem>
183 </varlistentry>
184 </variablelist>
185 </para>
186 </refsect2>
187 <refsect2 role="enum" id="eggdbus-errordomain-org.freedesktop.PolicyKit1.Error."> <title>The org.freedesktop.PolicyKit1.Error.* Error Domain</title>
188 <para>
189 <programlisting>
190 {
191 org.freedesktop.PolicyKit1.Error.Failed,
192 org.freedesktop.PolicyKit1.Error.Cancelled,
193 org.freedesktop.PolicyKit1.Error.NotSupported,
194 org.freedesktop.PolicyKit1.Error.NotAuthorized,
195 org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique
196 }
197 </programlisting>
198 <para>
199 Errors that can be returned by various method calls.
200 </para>
201 <variablelist role="constant">
202 <varlistentry id="eggdbus-constant-Error.org.freedesktop.PolicyKit1.Error.Failed" role="constant">
203 <term><literal>org.freedesktop.PolicyKit1.Error.Failed</literal></term>
204 <listitem>
205 <para>
206 The operation failed.
207 </para>
208 </listitem>
209 </varlistentry>
210 <varlistentry id="eggdbus-constant-Error.org.freedesktop.PolicyKit1.Error.Cancelled" role="constant">
211 <term><literal>org.freedesktop.PolicyKit1.Error.Cancelled</literal></term>
212 <listitem>
213 <para>
214 The operation was cancelled.
215 </para>
216 </listitem>
217 </varlistentry>
218 <varlistentry id="eggdbus-constant-Error.org.freedesktop.PolicyKit1.Error.NotSupported" role="constant">
219 <term><literal>org.freedesktop.PolicyKit1.Error.NotSupported</literal></term>
220 <listitem>
221 <para>
222 The operation is not supported.
223 </para>
224 </listitem>
225 </varlistentry>
226 <varlistentry id="eggdbus-constant-Error.org.freedesktop.PolicyKit1.Error.NotAuthorized" role="constant">
227 <term><literal>org.freedesktop.PolicyKit1.Error.NotAuthorized</literal></term>
228 <listitem>
229 <para>
230 You are not authorized to perform the requested operation.
231 </para>
232 </listitem>
233 </varlistentry>
234 <varlistentry id="eggdbus-constant-Error.org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique" role="constant">
235 <term><literal>org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique</literal></term>
236 <listitem>
237 <para>
238 The passed <parameter>cancellation_id</parameter> is already in use.
239 </para>
240 </listitem>
241 </varlistentry>
242 </variablelist>
243 </para>
244 </refsect2>
245 <refsect2 role="enum" id="eggdbus-enum-AuthorityFeatures">
246 <title>The AuthorityFeatures Flags</title>
247 <para>
248 <programlisting>
249 {
250 None = 0x00000000,
251 TemporaryAuthorization = 0x00000001
252 }
253 </programlisting>
254 <para>
255 Flags describing features supported by the Authority implementation.
256 </para>
257 <variablelist role="constant">
258 <varlistentry id="eggdbus-constant-AuthorityFeatures.None" role="constant">
259 <term><literal>None</literal></term>
260 <listitem>
261 <para>
262 No flags set.
263 </para>
264 </listitem>
265 </varlistentry>
266 <varlistentry id="eggdbus-constant-AuthorityFeatures.TemporaryAuthorization" role="constant">
267 <term><literal>TemporaryAuthorization</literal></term>
268 <listitem>
269 <para>
270 The authority supports temporary authorizations that can be obtained through authentication.
271 </para>
272 </listitem>
273 </varlistentry>
274 </variablelist>
275 </para>
276 </refsect2>
277 </refsect1>
278 <refsect1 role="desc" id="eggdbus-if-structures-org.freedesktop.PolicyKit1.Authority">
279 <title role="desc.title">Structures</title>
280 <refsect2 role="struct" id="eggdbus-struct-Subject">
281 <title>The Subject Structure</title>
282 <para>
283 <programlisting>
284 {
285 String subject_kind,
286 Dict&lt;String,Variant&gt; subject_details
287 }
288 </programlisting>
289 <para>
290 <para>This struct describes subjects such as UNIX processes. It is typically used to check if a given process is authorized for an action.</para><para>The following kinds of subjects are known:</para> <formalpara><title>Unix Process</title><para><literal>subject_kind</literal> should be set to <literal>unix-process</literal> with keys <literal>pidfd</literal> (of type <literal>int32</literal>) and <literal>uid</literal> (of type <literal>int32</literal>) (if the operating system supports ProcessID File Descriptors), or alternatively with keys <literal>pid</literal> (of type <literal>uint32</literal>), <literal>uid</literal> (of type <literal>int32</literal>) and <literal>start-time</literal> (of type <literal>uint64</literal>).</para></formalpara> <formalpara><title>Unix Session</title><para><literal>subject_kind</literal> should be set to <literal>unix-session</literal> with the key <literal>session-id</literal> (of type <literal>string</literal>).</para></formalpara> <formalpara><title>System Bus Name</title><para><literal>subject_kind</literal> should be set to <literal>system-bus-name</literal> with the key <literal>name</literal> (of type <literal>string</literal>).</para></formalpara>
291 </para>
292 <variablelist role="struct">
293 <varlistentry>
294 <term><literal>String <structfield>subject_kind</structfield></literal></term>
295 <listitem>
296 <para>
297 The type of the subject.
298 </para>
299 </listitem>
300 </varlistentry>
301 <varlistentry>
302 <term><literal>Dict&lt;String,Variant&gt; <structfield>subject_details</structfield></literal></term>
303 <listitem>
304 <para>
305 Details about the subject. Depending of the value of <parameter>subject_kind</parameter>, a set of well-defined key/value pairs are guaranteed to be available.
306 </para>
307 </listitem>
308 </varlistentry>
309 </variablelist>
310 </para>
311 </refsect2>
312 <refsect2 role="struct" id="eggdbus-struct-Identity">
313 <title>The Identity Structure</title>
314 <para>
315 <programlisting>
316 {
317 String identity_kind,
318 Dict&lt;String,Variant&gt; identity_details
319 }
320 </programlisting>
321 <para>
322 <para>This struct describes identities such as UNIX users and UNIX groups. It is typically used to check if a given process is authorized for an action.</para><para>The following kinds of identities are known:</para> <formalpara><title>Unix User</title><para><literal>identity_kind</literal> should be set to <literal>unix-user</literal> with key <literal>uid</literal> (of type <literal>uint32</literal>).</para></formalpara> <formalpara><title>Unix Group</title><para><literal>identity_kind</literal> should be set to <literal>unix-group</literal> with key <literal>gid</literal> (of type <literal>uint32</literal>).</para></formalpara>
323 </para>
324 <variablelist role="struct">
325 <varlistentry>
326 <term><literal>String <structfield>identity_kind</structfield></literal></term>
327 <listitem>
328 <para>
329 Type of identity.
330 </para>
331 </listitem>
332 </varlistentry>
333 <varlistentry>
334 <term><literal>Dict&lt;String,Variant&gt; <structfield>identity_details</structfield></literal></term>
335 <listitem>
336 <para>
337 Details about the identity. Depending of the value of <parameter>identity_kind</parameter>, a set of well-defined key/value pairs are guaranteed to be available.
338 </para>
339 </listitem>
340 </varlistentry>
341 </variablelist>
342 </para>
343 </refsect2>
344 <refsect2 role="struct" id="eggdbus-struct-ActionDescription">
345 <title>The ActionDescription Structure</title>
346 <para>
347 <programlisting>
348 {
349 String action_id,
350 String description,
351 String message,
352 String vendor_name,
353 String vendor_url,
354 String icon_name,
355 <link linkend="eggdbus-enum-ImplicitAuthorization">ImplicitAuthorization</link> implicit_any,
356 <link linkend="eggdbus-enum-ImplicitAuthorization">ImplicitAuthorization</link> implicit_inactive,
357 <link linkend="eggdbus-enum-ImplicitAuthorization">ImplicitAuthorization</link> implicit_active,
358 Dict&lt;String,String&gt; annotations
359 }
360 </programlisting>
361 <para>
362 This struct describes actions registered with the PolicyKit daemon.
363 </para>
364 <variablelist role="struct">
365 <varlistentry>
366 <term><literal>String <structfield>action_id</structfield></literal></term>
367 <listitem>
368 <para>
369 Action Identifier.
370 </para>
371 </listitem>
372 </varlistentry>
373 <varlistentry>
374 <term><literal>String <structfield>description</structfield></literal></term>
375 <listitem>
376 <para>
377 Localized description of the action.
378 </para>
379 </listitem>
380 </varlistentry>
381 <varlistentry>
382 <term><literal>String <structfield>message</structfield></literal></term>
383 <listitem>
384 <para>
385 Localized message to be displayed when making the user authenticate for an action.
386 </para>
387 </listitem>
388 </varlistentry>
389 <varlistentry>
390 <term><literal>String <structfield>vendor_name</structfield></literal></term>
391 <listitem>
392 <para>
393 Name of the provider of the action or the empty string.
394 </para>
395 </listitem>
396 </varlistentry>
397 <varlistentry>
398 <term><literal>String <structfield>vendor_url</structfield></literal></term>
399 <listitem>
400 <para>
401 A URL pointing to a place with more information about the action or the empty string.
402 </para>
403 </listitem>
404 </varlistentry>
405 <varlistentry>
406 <term><literal>String <structfield>icon_name</structfield></literal></term>
407 <listitem>
408 <para>
409 The themed icon describing the action or the empty string if no icon is set.
410 </para>
411 </listitem>
412 </varlistentry>
413 <varlistentry>
414 <term><literal><link linkend="eggdbus-enum-ImplicitAuthorization">ImplicitAuthorization</link> <structfield>implicit_any</structfield></literal></term>
415 <listitem>
416 <para>
417 A value from the <link linkend="eggdbus-enum-ImplicitAuthorization">ImplicitAuthorization</link>. enumeration for implicit authorizations that apply to any <link linkend="eggdbus-struct-Subject">Subject</link>.
418 </para>
419 </listitem>
420 </varlistentry>
421 <varlistentry>
422 <term><literal><link linkend="eggdbus-enum-ImplicitAuthorization">ImplicitAuthorization</link> <structfield>implicit_inactive</structfield></literal></term>
423 <listitem>
424 <para>
425 A value from the <link linkend="eggdbus-enum-ImplicitAuthorization">ImplicitAuthorization</link>. enumeration for implicit authorizations that apply any <link linkend="eggdbus-struct-Subject">Subject</link> in an inactive user session on the local console.
426 </para>
427 </listitem>
428 </varlistentry>
429 <varlistentry>
430 <term><literal><link linkend="eggdbus-enum-ImplicitAuthorization">ImplicitAuthorization</link> <structfield>implicit_active</structfield></literal></term>
431 <listitem>
432 <para>
433 A value from the <link linkend="eggdbus-enum-ImplicitAuthorization">ImplicitAuthorization</link>. enumeration for implicit authorizations that apply any <link linkend="eggdbus-struct-Subject">Subject</link> in an active user session on the local console.
434 </para>
435 </listitem>
436 </varlistentry>
437 <varlistentry>
438 <term><literal>Dict&lt;String,String&gt; <structfield>annotations</structfield></literal></term>
439 <listitem>
440 <para>
441 Annotations for the action.
442 </para>
443 </listitem>
444 </varlistentry>
445 </variablelist>
446 </para>
447 </refsect2>
448 <refsect2 role="struct" id="eggdbus-struct-AuthorizationResult">
449 <title>The AuthorizationResult Structure</title>
450 <para>
451 <programlisting>
452 {
453 Boolean is_authorized,
454 Boolean is_challenge,
455 Dict&lt;String,String&gt; details
456 }
457 </programlisting>
458 <para>
459 Describes the result of calling <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CheckAuthorization">CheckAuthorization()</link>.
460 </para>
461 <variablelist role="struct">
462 <varlistentry>
463 <term><literal>Boolean <structfield>is_authorized</structfield></literal></term>
464 <listitem>
465 <para>
466 TRUE if the given <link linkend="eggdbus-struct-Subject">Subject</link> is authorized for the given action.
467 </para>
468 </listitem>
469 </varlistentry>
470 <varlistentry>
471 <term><literal>Boolean <structfield>is_challenge</structfield></literal></term>
472 <listitem>
473 <para>
474 TRUE if the given <link linkend="eggdbus-struct-Subject">Subject</link> could be authorized if more information was provided, and <link linkend="eggdbus-constant-CheckAuthorizationFlags.AllowUserInteraction">CheckAuthorizationFlags.AllowUserInteraction</link> wasn't passed or no suitable authentication agent was available.
475 </para>
476 </listitem>
477 </varlistentry>
478 <varlistentry>
479 <term><literal>Dict&lt;String,String&gt; <structfield>details</structfield></literal></term>
480 <listitem>
481 <para>
482 Details for the result. Known key/value-pairs include <literal>polkit.temporary_authorization_id</literal> (if the authorization is temporary, this is set to the opaque temporary authorization id), <literal>polkit.retains_authorization_after_challenge</literal> (Set to a non-empty string if the authorization will be retained after authentication (if is_challenge is TRUE)), <literal>polkit.dismissed</literal> (Set to a non-empty string if the authentication dialog was dismissed by the user), <literal>polkit.result</literal> (Set to the string value of the polkit.Result enum, e.g.: <literal>auth_admin</literal>).
483 </para>
484 </listitem>
485 </varlistentry>
486 </variablelist>
487 </para>
488 </refsect2>
489 <refsect2 role="struct" id="eggdbus-struct-TemporaryAuthorization">
490 <title>The TemporaryAuthorization Structure</title>
491 <para>
492 <programlisting>
493 {
494 String id,
495 String action_id,
496 <link linkend="eggdbus-struct-Subject">Subject</link> subject,
497 UInt64 time_obtained,
498 UInt64 time_expires
499 }
500 </programlisting>
501 <para>
502 This struct describes a temporary authorization.
503 </para>
504 <variablelist role="struct">
505 <varlistentry>
506 <term><literal>String <structfield>id</structfield></literal></term>
507 <listitem>
508 <para>
509 An opaque identifier for the temporary authorization.
510 </para>
511 </listitem>
512 </varlistentry>
513 <varlistentry>
514 <term><literal>String <structfield>action_id</structfield></literal></term>
515 <listitem>
516 <para>
517 The action the temporary authorization is for.
518 </para>
519 </listitem>
520 </varlistentry>
521 <varlistentry>
522 <term><literal><link linkend="eggdbus-struct-Subject">Subject</link> <structfield>subject</structfield></literal></term>
523 <listitem>
524 <para>
525 The subject the temporary authorization is for.
526 </para>
527 </listitem>
528 </varlistentry>
529 <varlistentry>
530 <term><literal>UInt64 <structfield>time_obtained</structfield></literal></term>
531 <listitem>
532 <para>
533 When the temporary authorization was obtained, in seconds since the Epoch Jan 1, 1970 0:00 UTC.
534 Note that the PolicyKit daemon is using monotonic time internally so the returned value may change if system time changes.
535 </para>
536 </listitem>
537 </varlistentry>
538 <varlistentry>
539 <term><literal>UInt64 <structfield>time_expires</structfield></literal></term>
540 <listitem>
541 <para>
542 When the temporary authorization is set to expire, in seconds since the Epoch Jan 1, 1970 0:00 UTC.
543 Note that the PolicyKit daemon is using monotonic time internally so the returned value may change if system time changes.
544 </para>
545 </listitem>
546 </varlistentry>
547 </variablelist>
548 </para>
549 </refsect2>
550 </refsect1>
551 <refsect1 role="details" id="eggdbus-if-method-details-org.freedesktop.PolicyKit1.Authority">
552 <title role="details.title">Method Details</title>
553 <refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.Authority.EnumerateActions">
554 <title>EnumerateActions ()</title>
555 <programlisting>
556 EnumerateActions (IN String locale,
557 OUT Array&lt;<link linkend="eggdbus-struct-ActionDescription">ActionDescription</link>&gt; action_descriptions)
558 </programlisting>
559 <para>
560 Enumerates all registered PolicyKit actions.
561 </para>
562 <variablelist role="params">
563 <varlistentry>
564 <term><literal>IN String <parameter>locale</parameter></literal>:</term>
565 <listitem>
566 <para>
567 The locale to get descriptions in or the blank string to use the system locale.
568 </para>
569 </listitem>
570 </varlistentry>
571 <varlistentry>
572 <term><literal>OUT Array&lt;<link linkend="eggdbus-struct-ActionDescription">ActionDescription</link>&gt; <parameter>action_descriptions</parameter></literal>:</term>
573 <listitem>
574 <para>
575 An array of <link linkend="eggdbus-struct-ActionDescription">ActionDescription</link> structs.
576 </para>
577 </listitem>
578 </varlistentry>
579 </variablelist>
580 </refsect2>
581 <refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CheckAuthorization">
582 <title>CheckAuthorization ()</title>
583 <programlisting>
584 CheckAuthorization (IN <link linkend="eggdbus-struct-Subject">Subject</link> subject,
585 IN String action_id,
586 IN Dict&lt;String,String&gt; details,
587 IN <link linkend="eggdbus-enum-CheckAuthorizationFlags">CheckAuthorizationFlags</link> flags,
588 IN String cancellation_id,
589 OUT <link linkend="eggdbus-struct-AuthorizationResult">AuthorizationResult</link> result)
590 </programlisting>
591 <para>
592 <para>
593 Checks if <parameter>subject</parameter> is authorized to
594 perform the action with identifier
595 <parameter>action_id</parameter>
596 </para>
597 <para>
598 If <parameter>cancellation_id</parameter> is non-empty and
599 already in use for the caller, the <link
600 linkend="eggdbus-constant-Error.org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique">org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique</link>
601 error is returned.
602 </para>
603 <para>
604 Note that <link
605 linkend="eggdbus-constant-CheckAuthorizationFlags.AllowUserInteraction">CheckAuthorizationFlags.AllowUserInteraction</link>
606 SHOULD be passed ONLY if the event that triggered the
607 authorization check is stemming from an user action, e.g. the
608 user pressing a button or attaching a device.
609 </para>
610 <para>
611 </para>
612 </para>
613 <variablelist role="params">
614 <varlistentry>
615 <term><literal>IN <link linkend="eggdbus-struct-Subject">Subject</link> <parameter>subject</parameter></literal>:</term>
616 <listitem>
617 <para>
618 A <link linkend="eggdbus-struct-Subject">Subject</link> struct.
619 </para>
620 </listitem>
621 </varlistentry>
622 <varlistentry>
623 <term><literal>IN String <parameter>action_id</parameter></literal>:</term>
624 <listitem>
625 <para>
626 Identifier for the action that <parameter>subject</parameter> is attempting to do.
627 </para>
628 </listitem>
629 </varlistentry>
630 <varlistentry>
631 <term><literal>IN Dict&lt;String,String&gt; <parameter>details</parameter></literal>:</term>
632 <listitem>
633 <para>
634 Details describing the action. Keys starting with <literal>polkit.</literal> are can only be set if defined in this document.
635 </para>
636 <para>
637 Known keys include <literal>polkit.message</literal> and
638 <literal>polkit.gettext_domain</literal> that can be used to
639 override the message shown to the user. This latter is needed
640 because the user could be running an authentication agent in
641 another locale than the calling process.
642 </para>
643 <para>
644 The (translated version of) <literal>polkit.message</literal>
645 may include references to other keys that are expanded with
646 their respective values. For example if the key
647 <literal>device_file</literal> has the value
648 <literal>/dev/sda</literal> then the message
649 "<literal>Authenticate to format $(device_file)</literal>" is
650 expanded to "<literal>Authenticate to format
651 /dev/sda</literal>".
652 </para>
653 <para>
654 The key <literal>polkit.icon_name</literal> is used to override the icon shown in the authentication dialog.
655 </para>
656 <para>
657 If non-empty, then the request will fail with
658 <link linkend="eggdbus-constant-Error.org.freedesktop.PolicyKit1.Error.Failed">org.freedesktop.PolicyKit1.Error.Failed</link>
659 unless the process doing the check itself is sufficiently authorized (e.g. running as uid 0).
660 </para>
661 </listitem>
662 </varlistentry>
663 <varlistentry>
664 <term><literal>IN <link linkend="eggdbus-enum-CheckAuthorizationFlags">CheckAuthorizationFlags</link> <parameter>flags</parameter></literal>:</term>
665 <listitem>
666 <para>
667 A set of <link linkend="eggdbus-enum-CheckAuthorizationFlags">CheckAuthorizationFlags</link>.
668 </para>
669 </listitem>
670 </varlistentry>
671 <varlistentry>
672 <term><literal>IN String <parameter>cancellation_id</parameter></literal>:</term>
673 <listitem>
674 <para>
675 A unique id used to cancel the the authentication check via <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CancelCheckAuthorization">CancelCheckAuthorization()</link> or the empty string if cancellation is not needed.
676 </para>
677 </listitem>
678 </varlistentry>
679 <varlistentry>
680 <term><literal>OUT <link linkend="eggdbus-struct-AuthorizationResult">AuthorizationResult</link> <parameter>result</parameter></literal>:</term>
681 <listitem>
682 <para>
683 An <link linkend="eggdbus-struct-AuthorizationResult">AuthorizationResult</link> structure.
684 </para>
685 </listitem>
686 </varlistentry>
687 </variablelist>
688 </refsect2>
689 <refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CancelCheckAuthorization">
690 <title>CancelCheckAuthorization ()</title>
691 <programlisting>
692 CancelCheckAuthorization (IN String cancellation_id)
693 </programlisting>
694 <para>
695 Cancels an authorization check.
696 </para>
697 <variablelist role="params">
698 <varlistentry>
699 <term><literal>IN String <parameter>cancellation_id</parameter></literal>:</term>
700 <listitem>
701 <para>
702 The <parameter>cancellation_id</parameter> passed to <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.CheckAuthorization">CheckAuthorization()</link>.
703 </para>
704 </listitem>
705 </varlistentry>
706 </variablelist>
707 </refsect2>
708 <refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">
709 <title>RegisterAuthenticationAgent ()</title>
710 <programlisting>
711 RegisterAuthenticationAgent (IN <link linkend="eggdbus-struct-Subject">Subject</link> subject,
712 IN String locale,
713 IN String object_path)
714 </programlisting>
715 <para>
716 <para>Register an authentication agent.</para><para>Note that this should be called by same effective UID which will be passed to <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2">AuthenticationAgentResponse2()</link>.</para>
717 </para>
718 <variablelist role="params">
719 <varlistentry>
720 <term><literal>IN <link linkend="eggdbus-struct-Subject">Subject</link> <parameter>subject</parameter></literal>:</term>
721 <listitem>
722 <para>
723 The subject to register the authentication agent for, typically a session subject.
724 </para>
725 </listitem>
726 </varlistentry>
727 <varlistentry>
728 <term><literal>IN String <parameter>locale</parameter></literal>:</term>
729 <listitem>
730 <para>
731 The locale of the authentication agent.
732 </para>
733 </listitem>
734 </varlistentry>
735 <varlistentry>
736 <term><literal>IN String <parameter>object_path</parameter></literal>:</term>
737 <listitem>
738 <para>
739 The object path of authentication agent object on the unique name of the caller.
740 </para>
741 </listitem>
742 </varlistentry>
743 </variablelist>
744 </refsect2>
745
746 <refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgentWithOptions">
747 <title>RegisterAuthenticationAgentWithOptions ()</title>
748 <programlisting>
749 RegisterAuthenticationAgentWithOptions (IN <link linkend="eggdbus-struct-Subject">Subject</link> subject,
750 IN String locale,
751 IN String object_path,
752 IN Dict&lt;String,Variant&gt; options)
753 </programlisting>
754 <para>
755 <para>Like <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent</link> but takes additional options. If the option <literal>fallback</literal> (of type <literal>Boolean</literal>) is TRUE, then the authentcation agent will only be used as a fallback, e.g. if another agent (without the <literal>fallback</literal> option set TRUE) is available, it will be used instead.</para>
756 </para>
757 </refsect2>
758
759 <refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.Authority.UnregisterAuthenticationAgent">
760 <title>UnregisterAuthenticationAgent ()</title>
761 <programlisting>
762 UnregisterAuthenticationAgent (IN <link linkend="eggdbus-struct-Subject">Subject</link> subject,
763 IN String object_path)
764 </programlisting>
765 <para>
766 Unregister an authentication agent.
767 </para>
768 <variablelist role="params">
769 <varlistentry>
770 <term><literal>IN <link linkend="eggdbus-struct-Subject">Subject</link> <parameter>subject</parameter></literal>:</term>
771 <listitem>
772 <para>
773 The <parameter>subject</parameter> passed to <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent()</link>.
774 </para>
775 </listitem>
776 </varlistentry>
777 <varlistentry>
778 <term><literal>IN String <parameter>object_path</parameter></literal>:</term>
779 <listitem>
780 <para>
781 The <parameter>object_path</parameter> passed to <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent()</link>.
782 </para>
783 </listitem>
784 </varlistentry>
785 </variablelist>
786 </refsect2>
787 <refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse">
788 <title>AuthenticationAgentResponse ()</title>
789 <programlisting>
790 AuthenticationAgentResponse (IN String cookie,
791 IN <link linkend="eggdbus-struct-Identity">Identity</link> identity)
792 </programlisting>
793 <para>
794 Method for authentication agents to invoke on successful
795 authentication, intended only for use by a privileged helper process
796 internal to polkit. This method will fail unless a sufficiently privileged
797 +caller invokes it. Deprecated in favor of <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2">AuthenticationAgentResponse2()</link>.
798 </para>
799 <variablelist role="params">
800 <varlistentry>
801 <term><literal>IN String <parameter>cookie</parameter></literal>:</term>
802 <listitem>
803 <para>
804 The cookie identifying the authentication request that was passed to the authentication agent.
805 </para>
806 </listitem>
807 </varlistentry>
808 <varlistentry>
809 <term><literal>IN <link linkend="eggdbus-struct-Identity">Identity</link> <parameter>identity</parameter></literal>:</term>
810 <listitem>
811 <para>
812 A <link linkend="eggdbus-struct-Identity">Identity</link> struct describing what identity was authenticated.
813 </para>
814 </listitem>
815 </varlistentry>
816 </variablelist>
817 </refsect2>
818 <refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2">
819 <title>AuthenticationAgentResponse2 ()</title>
820 <programlisting>
821 AuthenticationAgentResponse2 (IN uint32 uid,
822 IN String cookie,
823 IN <link linkend="eggdbus-struct-Identity">Identity</link> identity)
824 </programlisting>
825 <para>
826 Method for authentication agents to invoke on successful
827 authentication, intended only for use by a privileged helper process
828 internal to polkit. This method will fail unless a sufficiently privileged
829 caller invokes it. Note this method was introduced in 0.114 and should be
830 preferred over <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse">AuthenticationAgentResponse()</link>
831 as it fixes a security issue.
832 </para>
833 <variablelist role="params">
834 <varlistentry>
835 <term><literal>IN uint32 <parameter>uid</parameter></literal>:</term>
836 <listitem>
837 <para>
838 The user id of the agent; normally this is the owner of the parent pid
839 of the process that invoked the internal setuid helper.
840 </para>
841 </listitem>
842 </varlistentry>
843 <varlistentry>
844 <term><literal>IN String <parameter>cookie</parameter></literal>:</term>
845 <listitem>
846 <para>
847 The cookie identifying the authentication request that was passed to the authentication agent.
848 </para>
849 </listitem>
850 </varlistentry>
851 <varlistentry>
852 <term><literal>IN <link linkend="eggdbus-struct-Identity">Identity</link> <parameter>identity</parameter></literal>:</term>
853 <listitem>
854 <para>
855 A <link linkend="eggdbus-struct-Identity">Identity</link> struct describing what identity was authenticated.
856 </para>
857 </listitem>
858 </varlistentry>
859 </variablelist>
860 </refsect2>
861 <refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse3">
862 <title>AuthenticationAgentResponse3 ()</title>
863 <programlisting>
864 AuthenticationAgentResponse3 (IN String cookie,
865 IN <link linkend="eggdbus-struct-Identity">Identity</link> identity,
866 IN <link linkend="eggdbus-struct-Subject">Subject</link> subject)
867 </programlisting>
868 <para>
869 Method for authentication agents to invoke on successful
870 authentication, intended only for use by a privileged helper process
871 running via socket activation. This method will fail unless a sufficiently privileged
872 caller invokes it. In contract to other methods this takes a subject as input, which
873 allows reliably tracking the requester via PID FD.
874 </para>
875 <variablelist role="params">
876 <varlistentry>
877 <term><literal>IN String <parameter>cookie</parameter></literal>:</term>
878 <listitem>
879 <para>
880 The cookie identifying the authentication request that was passed to the authentication agent.
881 </para>
882 </listitem>
883 </varlistentry>
884 <varlistentry>
885 <term><literal>IN <link linkend="eggdbus-struct-Identity">Identity</link> <parameter>identity</parameter></literal>:</term>
886 <listitem>
887 <para>
888 A <link linkend="eggdbus-struct-Identity">Identity</link> struct describing what identity was authenticated.
889 </para>
890 </listitem>
891 </varlistentry>
892 <varlistentry>
893 <term><literal>IN <link linkend="eggdbus-struct-Subject">Subject</link> <parameter>subject</parameter></literal>:</term>
894 <listitem>
895 <para>
896 A <link linkend="eggdbus-struct-Subject">Subject</link> struct describing what entity requested the authentication.
897 </para>
898 </listitem>
899 </varlistentry>
900 </variablelist>
901 </refsect2>
902 <refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.Authority.EnumerateTemporaryAuthorizations">
903 <title>EnumerateTemporaryAuthorizations ()</title>
904 <programlisting>
905 EnumerateTemporaryAuthorizations (IN <link linkend="eggdbus-struct-Subject">Subject</link> subject,
906 OUT Array&lt;<link linkend="eggdbus-struct-TemporaryAuthorization">TemporaryAuthorization</link>&gt; temporary_authorizations)
907 </programlisting>
908 <para>
909 Retrieves all temporary authorizations that applies to <parameter>subject</parameter>.
910 </para>
911 <variablelist role="params">
912 <varlistentry>
913 <term><literal>IN <link linkend="eggdbus-struct-Subject">Subject</link> <parameter>subject</parameter></literal>:</term>
914 <listitem>
915 <para>
916 The subject to get temporary authorizations for.
917 </para>
918 </listitem>
919 </varlistentry>
920 <varlistentry>
921 <term><literal>OUT Array&lt;<link linkend="eggdbus-struct-TemporaryAuthorization">TemporaryAuthorization</link>&gt; <parameter>temporary_authorizations</parameter></literal>:</term>
922 <listitem>
923 <para>
924 An array of <link linkend="eggdbus-struct-TemporaryAuthorization">TemporaryAuthorization</link> structs.
925 </para>
926 </listitem>
927 </varlistentry>
928 </variablelist>
929 </refsect2>
930 <refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RevokeTemporaryAuthorizations">
931 <title>RevokeTemporaryAuthorizations ()</title>
932 <programlisting>
933 RevokeTemporaryAuthorizations (IN <link linkend="eggdbus-struct-Subject">Subject</link> subject)
934 </programlisting>
935 <para>
936 Revokes all temporary authorizations that applies to <parameter>subject</parameter>.
937 </para>
938 <variablelist role="params">
939 <varlistentry>
940 <term><literal>IN <link linkend="eggdbus-struct-Subject">Subject</link> <parameter>subject</parameter></literal>:</term>
941 <listitem>
942 <para>
943 The subject to revoke temporary authorizations from.
944 </para>
945 </listitem>
946 </varlistentry>
947 </variablelist>
948 </refsect2>
949 <refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RevokeTemporaryAuthorizationById">
950 <title>RevokeTemporaryAuthorizationById ()</title>
951 <programlisting>
952 RevokeTemporaryAuthorizationById (IN String id)
953 </programlisting>
954 <para>
955 Revokes all temporary authorizations that applies to <parameter>subject</parameter>.
956 </para>
957 <variablelist role="params">
958 <varlistentry>
959 <term><literal>IN String <parameter>id</parameter></literal>:</term>
960 <listitem>
961 <para>
962 The opaque identifier of the temporary authorization.
963 </para>
964 </listitem>
965 </varlistentry>
966 </variablelist>
967 </refsect2>
968 </refsect1>
969 <refsect1 role="signals" id="eggdbus-if-signal-details-org.freedesktop.PolicyKit1.Authority">
970 <title role="signals.title">Signal Details</title>
971 <refsect2 role="signal" id="eggdbus-signal-org.freedesktop.PolicyKit1.Authority::Changed">
972 <title>The "Changed" signal</title>
973 <programlisting>
974 Changed ()
975 </programlisting>
976 <para>
977 This signal is emitted when actions and/or authorizations change
978 </para>
979 <variablelist role="params">
980 </variablelist>
981 </refsect2>
982 </refsect1>
983 <refsect1 role="property_details" id="eggdbus-if-property-details-org.freedesktop.PolicyKit1.Authority">
984 <title role="property_details.title">Property Details</title>
985 <refsect2 role="property" id="eggdbus-property-org.freedesktop.PolicyKit1.Authority:BackendName">
986 <title>The "BackendName" property</title>
987 <programlisting>
988 BackendName readable String
989 </programlisting>
990 <para>
991 The name of the currently used Authority backend.
992 </para>
993 </refsect2>
994 <refsect2 role="property" id="eggdbus-property-org.freedesktop.PolicyKit1.Authority:BackendVersion">
995 <title>The "BackendVersion" property</title>
996 <programlisting>
997 BackendVersion readable String
998 </programlisting>
999 <para>
1000 The version of the currently used Authority backend.
1001 </para>
1002 </refsect2>
1003 <refsect2 role="property" id="eggdbus-property-org.freedesktop.PolicyKit1.Authority:BackendFeatures">
1004 <title>The "BackendFeatures" property</title>
1005 <programlisting>
1006 BackendFeatures readable <link linkend="eggdbus-enum-AuthorityFeatures">AuthorityFeatures</link>
1007 </programlisting>
1008 <para>
1009 The features supported by the currently used Authority backend.
1010 </para>
1011 </refsect2>
1012 </refsect1>
1013 </refentry>