{ "content": [ { "type": "text", "text": "# POLKIT (man)\n\n## NAME\n\npolkit - Authorization Framework\n\n## Sections\n\n- **NAME**\n- **OVERVIEW**\n- **SYSTEM ARCHITECTURE**\n- **AUTHENTICATION AGENTS**\n- **DECLARING ACTIONS** (1 subsections)\n- **AUTHOR**\n- **BUGS**\n- **SEE ALSO**\n- **NOTES**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "POLKIT", "section": "", "mode": "man", "summary": "polkit - Authorization Framework", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "pklocalauthority", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/pklocalauthority/8/json" }, { "name": "polkitd", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/polkitd/8/json" }, { "name": "pkaction", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pkaction/1/json" }, { "name": "pkcheck", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pkcheck/1/json" }, { "name": "pkexec", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pkexec/1/json" }, { "name": "pkttyagent", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pkttyagent/1/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "OVERVIEW", "lines": 12, "subsections": [] }, { "name": "SYSTEM ARCHITECTURE", "lines": 54, "subsections": [] }, { "name": "AUTHENTICATION AGENTS", "lines": 69, "subsections": [] }, { "name": "DECLARING ACTIONS", "lines": 101, "subsections": [ { "name": "Known annotations", "lines": 17 } ] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "BUGS", "lines": 3, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "NOTES", "lines": 15, "subsections": [] } ], "sections": { "NAME": { "content": "polkit - Authorization Framework\n", "subsections": [] }, "OVERVIEW": { "content": "PolicyKit provides an authorization API intended to be used by privileged programs\n(“MECHANISMS”) offering service to unprivileged programs (“CLIENTS”) through some form of IPC\nmechanism such as D-Bus or Unix pipes. In this scenario, the mechanism typically treats the\nclient as untrusted. For every request from a client, the mechanism needs to determine if the\nrequest is authorized or if it should refuse to service the client. Using the PolicyKit API,\na mechanism can offload this decision to a trusted party: The PolicyKit Authority.\n\nIn addition to acting as an authority, PolicyKit allows users to obtain temporary\nauthorization through authenticating either an administrative user or the owner of the\nsession the client belongs to. This is useful for scenarios where a mechanism needs to verify\nthat the operator of the system really is the user or really is an administrative user.\n", "subsections": [] }, "SYSTEM ARCHITECTURE": { "content": "The system architecture of PolicyKit is comprised of the Authority (implemented as a service\non the system message bus) and a Authentication Agent per user session (provided and started\nby the user session e.g. GNOME or KDE). Additionally, PolicyKit supports a number of\nextension points – specifically, vendors and/or sites can write extensions to completely\ncontrol authorization policy. In a block diagram, the architecture looks like this:\n\n[IMAGE][1]\n\n+-------------------+\n| Authentication |\n| Agent |\n+-------------------+\n| libpolkit-agent-1 |\n+-------------------+\n^ +--------+\n| | Client |\n+--------------+ +--------+\n| ^\n| |\nUser Session | |\n=======================|========================|=============\nSystem Context | |\n| |\n| +---+\nV |\n/------------\\ |\n| System Bus | |\n\\------------/ |\n^ ^ V\n| | +---------------------+\n+--------------+ | | Mechanism |\n| | +---------------------+\nV +----> | libpolkit-gobject-1 |\n+------------------+ +---------------------+\n| org.freedesktop. |\n| PolicyKit1 |\n+------------------+\n| Backends and |\n| Extensions |\n+------------------+\n\nFor convenience, the libpolkit-gobject-1 library wraps the PolicyKit D-Bus API using GObject.\nHowever, a mechanism can also use the D-Bus API or the pkcheck(1) command to check\nauthorizations.\n\nThe libpolkit-agent-1 library provides an abstraction of the native authentication system,\ne.g. pam(8) and also facilities registration and communication with the PolicyKit D-Bus\nservice.\n\nSee the developer documentation[2] for more information about using and extending PolicyKit.\n\nSee pklocalauthority(8) for information about the Local Authority - the default authority\nimplementation shipped with PolicyKit.\n", "subsections": [] }, "AUTHENTICATION AGENTS": { "content": "An authentication agent is used to make the user of a session prove that the user of the\nsession really is the user (by authenticating as the user) or an administrative user (by\nauthenticating as a administrator). In order to integrate well with the rest of the user\nsession (e.g. match the look and feel), authentication agents are meant to be provided by the\nuser session that the user uses. For example, an authentication agent may look like this:\n\n[IMAGE][3]\n\n+----------------------------------------------------------+\n| Authenticate [X] |\n+----------------------------------------------------------+\n| |\n| [Icon] Authentication is required to run ATA SMART |\n| self tests |\n| |\n| An application is attempting to perform an |\n| action that requires privileges. Authentication |\n| as the super user is required to perform this |\n| action. |\n| |\n| Password for root: [] |\n| |\n| [V] Details: |\n| Drive: ATA INTEL SSDSA2MH08 (045C) |\n| Device: /dev/sda |\n| Action: org.fd.devicekit.disks.drive-ata-smart-selftest |\n| Vendor: The DeviceKit Project |\n| |\n| [Cancel] [Authenticate] |\n+----------------------------------------------------------+\n\nIf the system is configured without a root account it may allow you to select the\nadministrative user who is authenticating:\n\n[IMAGE][4]\n\n+----------------------------------------------------------+\n| Authenticate [X] |\n+----------------------------------------------------------+\n| |\n| [Icon] Authentication is required to run ATA SMART |\n| self tests |\n| |\n| An application is attempting to perform an |\n| action that requires privileges. Authentication |\n| as one of the users below is required to |\n| perform this action. |\n| |\n| [[Face] Patrick Bateman (bateman) [V]] |\n| |\n| Password for bateman: [] |\n| |\n| [V] Details: |\n| Drive: ATA INTEL SSDSA2MH08 (045C) |\n| Device: /dev/sda |\n| Action: org.fd.devicekit.disks.drive-ata-smart-selftest |\n| Vendor: The DeviceKit Project |\n| |\n| [Cancel] [Authenticate] |\n+----------------------------------------------------------+\n\nSee pklocalauthority(8) on how to set up the local authority implemention for systems without\na root account.\n\nApplications that do not run under a desktop environment (for example, if launched from a\nssh(1) login) may not have have an authentication agent associated with them. Such\napplications may use the PolkitAgentTextListener type or the pkttyagent(1) helper so the user\ncan authenticate using a textual interface.\n", "subsections": [] }, "DECLARING ACTIONS": { "content": "A mechanism need to declare a set of “ACTIONS” in order to use PolicyKit. Actions correspond\nto operations that clients can request the mechanism to carry out and are defined in XML\nfiles that the mechanism installs into the /usr/share/polkit-1/actions directory.\n\nPolicyKit actions are namespaced and can only contain the characters [a-z][0-9].- e.g.\nlower-case ASCII, digits, period and hyphen. Each XML file can contain more than one action\nbut all actions need to be in the same namespace and the file needs to be named after the\nnamespace and have the extension .policy.\n\nThe XML file must have the following doctype declaration\n\n\n\n\nThe policyconfig element must be present exactly once. Elements that can be used inside\npolicyconfig includes:\n\nvendor\nThe name of the project or vendor that is supplying the actions in the XML document.\nOptional.\n\nvendorurl\nA URL to the project or vendor that is supplying the actions in the XML document.\nOptional.\n\niconname\nAn icon representing the project or vendor that is supplying the actions in the XML\ndocument. The icon name must adhere to the Freedesktop.org Icon Naming Specification[5].\nOptional.\n\naction\nDeclares an action. The action name is specified using the id attribute and can only\ncontain the characters [a-z][0-9].- e.g. lower-case ASCII, digits, period and hyphen.\n\nElements that can be used inside action includes:\n\ndescription\nA human readable description of the action, e.g. “Install unsigned software”.\n\nmessage\nA human readable message displayed to the user when asking for credentials when\nauthentication is needed, e.g. “Installing unsigned software requires authentication”.\n\ndefaults\nThis element is used to specify implicit authorizations for clients.\n\nElements that can be used inside defaults includes:\n\nallowany\nImplicit authorizations that apply to any client. Optional.\n\nallowinactive\nImplicit authorizations that apply to clients in inactive sessions on local consoles.\nOptional.\n\nallowactive\nImplicit authorizations that apply to clients in active sessions on local consoles.\nOptional.\n\nEach of the allowany, allowinactive and allowactive elements can contain the following\nvalues:\n\nno\nNot authorized.\n\nyes\nAuthorized.\n\nauthself\nAuthentication by the owner of the session that the client originates from is\nrequired.\n\nauthadmin\nAuthentication by an administrative user is required.\n\nauthselfkeep\nLike authself but the authorization is kept for a brief period.\n\nauthadminkeep\nLike authadmin but the authorization is kept for a brief period.\n\nannotate\nUsed for annotating an action with a key/value pair. The key is specified using the the\nkey attribute and the value is specified using the value attribute. This element may\nappear zero or more times. See below for known annotations.\n\nvendor\nUsed for overriding the vendor on a per-action basis. Optional.\n\nvendorurl\nUsed for overriding the vendor URL on a per-action basis. Optional.\n\niconname\nUsed for overriding the icon name on a per-action basis. Optional.\n\nFor localization, description and message elements may occur multiple times with different\nxml:lang attributes.\n\nTo list installed PolicyKit actions, use the pkaction(1) command.\n", "subsections": [ { "name": "Known annotations", "content": "The org.freedesktop.policykit.exec.path annotation is used by the pkexec program shipped with\nPolicyKit - see the pkexec(1) man page for details.\n\nThe org.freedesktop.policykit.imply annotation (its value is a string containing a space\nseparated list of action identifiers) can be used to define meta actions. The way it works is\nthat if a subject is authorized for an action with this annotation, then it is also\nauthorized for any action specified by the annotation. A typical use of this annotation is\nwhen defining an UI shell with a single lock button that should unlock multiple actions from\ndistinct mechanisms.\n\nThe org.freedesktop.policykit.owner annotation can be used to define a set of users who can\nquery whether a client is authorized to perform this action. If this annotation is not\nspecified then only root can query whether a client running as a different user is authorized\nfor an action. The value of this annotation is a string containing a space separated list of\nPolkitIdentity entries, for example \"unix-user:42 unix-user:colord\". A typical use of this\nannotation is for a daemon process that runs as a system user rather than root.\n" } ] }, "AUTHOR": { "content": "Written by David Zeuthen with a lot of help from many others.\n", "subsections": [] }, "BUGS": { "content": "Please send bug reports to either the distribution or the polkit-devel mailing list, see the\nlink http://lists.freedesktop.org/mailman/listinfo/polkit-devel on how to subscribe.\n", "subsections": [] }, "SEE ALSO": { "content": "pklocalauthority(8) polkitd(8) pkaction(1), pkcheck(1), pkexec(1), pkttyagent(1)\n", "subsections": [] }, "NOTES": { "content": "1. /usr/share/gtk-doc/html/polkit-1/polkit-architecture.png\n\n2. developer documentation\nfile:///usr/share/gtk-doc/html/polkit-1/index.html\n\n3. /usr/share/gtk-doc/html/polkit-1/polkit-authentication-agent-example.png\n\n4. /usr/share/gtk-doc/html/polkit-1/polkit-authentication-agent-example-wheel.png\n\n5. Freedesktop.org Icon Naming Specification\nhttp://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html\n\n\n\npolkit January 2009 POLKIT(8)", "subsections": [] } } } }