Man Linux: Main Page and Category List

NAME

       polkit-auth - Manage authorizations

SYNOPSIS

       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]

DESCRIPTION

       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.

OPTIONS

       --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
           auth_*.

           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
           launched).

       --show-obtainable
           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
           org.freedesktop.policykit.read 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 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.

       --version
           Show version and exit.

       --help
           Show this information.

CONSTRAINTS

       One can put one or more constraints on an authorization. They are used
       to limit where the authorization 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
           secure.

       --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.

NOTES

       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 org.example.foo. 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
       org.example.foo 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.

COMPLETION

       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 org.freedesktop.policykit.read authorization, the
       completion function will fall back to completing on all registered
       actions.

BUGS

       Please send bug reports to either the distribution or the hal mailing
       list, see http://lists.freedesktop.org/mailman/listinfo/hal. to
       subscribe.

SEE ALSO

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