Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
POLKIT-AUTH(1)			  polkit-auth			POLKIT-AUTH(1)

       polkit-auth - Manage authorizations

       polkit-auth [--obtain action] [--show-obtainable]
		   [[--user user] --explicit]
		   [[--user user] --explicit-detail]
		   [[--user user] --grant action [--constraint constraint]*]
		   [[--user user] --block action [--constraint constraint]*]
		   [[--user user] --revoke action] [--version] [--help]

       polkit-auth is used to inspect, obtain, grant and revoke	PolicyKit
       authorizations. If invoked without any options, the authorizations of
       the calling process will	be printed.

       --obtain	action
	   Attempt to obtain an	authorization through authentication for the
	   given action. This is only useful for implicit authorizations
	   requiring authentication; e.g. when an appropriate stanza in	the
	   defaults section of the .policy file	for the	action specifies

	   The gained authorization will be constrained	as much	as possible
	   using the constraints specified in the section called
	   "CONSTRAINTS". For example, on a system running SELinux, if the
	   caller runs uses this tool to obtain	an authorization from a	shell
	   in a	desktop	in an active session, then constraints for local,
	   active, exe and selinux_context will	all be added.

	   If an Authentication	Agent (such as the one from PolicyKit-gnome)
	   is available	in the session,	it will	used for authentication	unless
	   the environment variable POLKIT_AUTH_FORCE_TEXT is set. If the
	   environment variable	POLKIT_AUTH_GRANT_TO_PID is set, the
	   authorization will be granted to that process id instead of the
	   invoking process (e.g. the shell from which polkit-auth is

	   Prints all actions that can be obtained via authentication and for
	   which an authorization does not exist.

       [--user user] --explicit
	   Show	explicit authorizations. Duplicates are	not printed. If	used
	   with	the --user option, the authorization is required.

       [--user user] --explicit-detail
	   Show	detailed information about explicit authorizations. In
	   contrast to the --explicit, duplicates are printed as several
	   authorizations with different scope and constraints may exist.

       [--user user] --grant action [--constraint constraint]*
	   Grant an authorization for an action. This is different than
	   --obtain insofar that the defaults stanza of	the .policy file is
	   not consulted. Optionally, one or more constraints on the granted
	   authorization can be	specified, see the section called
	   "CONSTRAINTS" for details. The authorization	needed to grant
	   authorizations is org.freedesktop.policykit.grant.

       [--user user] --block action [--constraint constraint]*
	   Grant an negative authorization for an action. Negative
	   authorizations are normally used to block users that	would normally
	   be authorized due to	implicit authorizations. Optionally, one or
	   more	constraints on the granted authorization can be	specified, see
	   the section called "CONSTRAINTS" for	details. The authorization
	   needed to grant negative authorizations is
	   org.freedesktop.policykit.grant if the "beneficiary"	is another

       [--user user] --revoke action
	   Revoke all authorizations for an action. If the user	is not
	   specified the calling user is used. The authorization
	   org.freedesktop.policykit.revoke is needed to revoke	authorizations
	   from	other users.

	   Show	version	and exit.

	   Show	this information.

       One can put one or more constraints on an authorization.	They are used
       to limit	where the authrorization applies. Presently the	following
       constraints are supported

       --constraint local
	   The caller must be in a session on a	local console attached to the
	   system. For example processes that belong to	remote XDMCP or	ssh
	   connections will fail to meet this constraint and as	such the
	   authorization with such a constraint	won't apply.

       --constraint active
	   The caller must be in an active session. This is typically used
	   with	a local	constraint to ensure that the caller is	only
	   authorized if his session is	in the foreground. This	is typically
	   used	for fast user switching	(multiple sessions on the same
	   console) to prevent inactive	sessions from doing privileged
	   operations like spying (using a webcam or a sound card) on the
	   current active session.

       --constraint exe:/path/to/program
	   The authorization is	constrained to processes for where executable
	   path	(/proc/pid/exe on Linux) matches the given path. See the
	   section called "NOTES" for limitations on why this may not be

       --constraint selinux_context:system_u:object_r:some_context_t
	   The authorization is	constrained to processes for where their
	   SELinux security context matches the	given context.

       Note that the executable	path for a process is not necessary reliable
       information and as such shouldn't be relied on 100% to make a security
       decision. In fact, this information is only trustworthy in situations
       where the given binary is securely locked down meaning that 1) it can't
       be ptrace(2)'d; 2) libc secure mode kicks in (e.g LD_PRELOAD won't
       work); 3) there are no other attack vectors (e.g. GTK_MODULES, X11,
       CORBA, D-Bus) to	patch running code into	the process.

       In other	words: the risk	of relying on constraining an authorization to
       a path of an executable is high.	Suppose	that the program
       /usr/bin/gullible obtains an authorization via authentication for the
       action We add a	constraint to say that the gained
       authorization only applies to processes for whom	/proc/pid/exe points
       to /usr/bin/gullible.

       Now enter /usr/bin/evil.	It knows that the program /usr/bin/gullible is
       not "securely locked down" (per the definition in the above paragraph).
       So /usr/bin/evil	simply sets LD_PRELOAD and execs /usr/bin/gullible and
       it can now run code in a	process	where /proc/pid/exe points to
       /usr/bin/gullible. Thus,	the recently gained authorization for applies.	Also, /usr/bin/evil could use a	host of	other
       attack vectors to run it's own code under the disguise of pretending to
       be /usr/bin/gullible.

       Specifically for	interpreted languages like Python and Mono it is the
       case that /proc/pid/exe always points to	/usr/bin/python	resp.
       /usr/bin/mono. Thus, it's not very useful to rely on that the result
       for this	function if you	want to	constrain an authorization to e.g.
       /usr/bin/tomboy or /usr/bin/banshee.

       It is however possible to write programs	that are "securely locked
       down" (per the definition in the	above paragraph); for example all
       properly	written	setuid and setgid programs are written in this way.

       PolicyKit ships with a collection of shell functions such that
       completion on users, actions and	constraints work when using the
       bash(1) shell. For completion to	properly work for polkit-auth,
       arguments should	be entered in the order	specified in this manual page;
       for example.  --user should be specified	before --revoke	to complete
       only on the authorizations the given user has. Note that	if the calling
       user lacks the authorization, the
       completion function will	fall back to completing	on all registered

       Please send bug reports to either the distribution or the hal mailing
       list, see to

       PolicyKit(8), PolicyKit.conf(5),	polkit-action(1)

PolicyKit			  August 2007			POLKIT-AUTH(1)


Want to link to this manual page? Use this URL:

home | help