| 1 |
<?xml version="1.0"?> |
| 2 |
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" |
| 3 |
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ |
| 4 |
<!ENTITY version SYSTEM "../version.xml"> |
| 5 |
]> |
| 6 |
<refentry id="pkcheck.1" xmlns:xi="http://www.w3.org/2003/XInclude"> |
| 7 |
<refentryinfo> |
| 8 |
<title>pkcheck</title> |
| 9 |
<date>May 2009</date> |
| 10 |
<productname>polkit</productname> |
| 11 |
</refentryinfo> |
| 12 |
|
| 13 |
<refmeta> |
| 14 |
<refentrytitle>pkcheck</refentrytitle> |
| 15 |
<manvolnum>1</manvolnum> |
| 16 |
<refmiscinfo class="version"></refmiscinfo> |
| 17 |
</refmeta> |
| 18 |
|
| 19 |
<refnamediv> |
| 20 |
<refname>pkcheck</refname> |
| 21 |
<refpurpose>Check whether a process is authorized</refpurpose> |
| 22 |
</refnamediv> |
| 23 |
|
| 24 |
<refsynopsisdiv> |
| 25 |
<cmdsynopsis> |
| 26 |
<command>pkcheck</command> |
| 27 |
<arg><option>--version</option></arg> |
| 28 |
<arg><option>--help|-h</option></arg> |
| 29 |
</cmdsynopsis> |
| 30 |
|
| 31 |
<cmdsynopsis> |
| 32 |
<command>pkcheck</command> |
| 33 |
<arg><option>--list-temp</option></arg> |
| 34 |
</cmdsynopsis> |
| 35 |
|
| 36 |
<cmdsynopsis> |
| 37 |
<command>pkcheck</command> |
| 38 |
<arg><option>--revoke-temp</option></arg> |
| 39 |
</cmdsynopsis> |
| 40 |
|
| 41 |
<cmdsynopsis> |
| 42 |
<command>pkcheck</command> |
| 43 |
<arg choice="plain"> |
| 44 |
<option>--action-id|-a</option> |
| 45 |
<replaceable>action</replaceable> |
| 46 |
</arg> |
| 47 |
|
| 48 |
<group choice="req"> |
| 49 |
<arg choice="plain"> |
| 50 |
<option>--process|-p</option> |
| 51 |
<group choice="req"> |
| 52 |
<arg choice="plain"> |
| 53 |
<replaceable>pid</replaceable> |
| 54 |
</arg> |
| 55 |
<arg choice="plain"> |
| 56 |
<replaceable>pid,pid-start-time</replaceable> |
| 57 |
</arg> |
| 58 |
<arg choice="plain"> |
| 59 |
<replaceable>pid,pid-start-time,uid</replaceable> |
| 60 |
</arg> |
| 61 |
</group> |
| 62 |
</arg> |
| 63 |
<arg choice="plain"> |
| 64 |
<option>--system-bus-name|-s</option> |
| 65 |
<replaceable>busname</replaceable> |
| 66 |
</arg> |
| 67 |
</group> |
| 68 |
|
| 69 |
<group> |
| 70 |
<arg choice="plain"> |
| 71 |
<option>--allow-user-interaction|-u</option> |
| 72 |
</arg> |
| 73 |
</group> |
| 74 |
|
| 75 |
<group> |
| 76 |
<arg choice="plain"> |
| 77 |
<option>--enable-internal-agent</option> |
| 78 |
</arg> |
| 79 |
</group> |
| 80 |
|
| 81 |
<group rep="repeat"> |
| 82 |
<arg choice="plain"> |
| 83 |
<option>--detail|-d</option> |
| 84 |
<replaceable>key</replaceable> |
| 85 |
<replaceable>value</replaceable> |
| 86 |
</arg> |
| 87 |
</group> |
| 88 |
</cmdsynopsis> |
| 89 |
|
| 90 |
</refsynopsisdiv> |
| 91 |
|
| 92 |
<refsect1 id="pkcheck-descsription"> |
| 93 |
<title>DESCRIPTION</title> |
| 94 |
<para> |
| 95 |
<command>pkcheck</command> is used to check whether a process, specified by |
| 96 |
either <option>--process</option> (see below) or <option>--system-bus-name</option>, |
| 97 |
is authorized for <replaceable>action</replaceable>. The <option>--detail</option> |
| 98 |
option can be used zero or more times to pass details about <replaceable>action</replaceable>. |
| 99 |
If <option>--allow-user-interaction</option> is passed, <command>pkcheck</command> blocks |
| 100 |
while waiting for authentication. |
| 101 |
</para> |
| 102 |
<para> |
| 103 |
The invocation <command>pkcheck --list-temp</command> will list |
| 104 |
all temporary authorizations for the current session and |
| 105 |
<command>pkcheck --revoke-temp</command> will revoke all |
| 106 |
temporary authorizations for the current session. |
| 107 |
</para> |
| 108 |
<para> |
| 109 |
This command is a simple wrapper around the polkit D-Bus interface; see the |
| 110 |
D-Bus interface documentation for details. |
| 111 |
</para> |
| 112 |
</refsect1> |
| 113 |
|
| 114 |
<refsect1 id="pkcheck-return-value"> |
| 115 |
<title>RETURN VALUE</title> |
| 116 |
<para> |
| 117 |
If the specified process is |
| 118 |
authorized, <command>pkcheck</command> exits with a return value |
| 119 |
of 0. If the authorization result contains any details, these |
| 120 |
are printed on standard output as key/value pairs using |
| 121 |
environment style reporting, e.g. first the key followed by a an equal sign, then the |
| 122 |
value followed by a newline. |
| 123 |
<programlisting> |
| 124 |
KEY1=VALUE1 |
| 125 |
KEY2=VALUE2 |
| 126 |
KEY3=VALUE3 |
| 127 |
...</programlisting> |
| 128 |
Octets that are not in [a-zA-Z0-9_] are escaped using octal codes prefixed |
| 129 |
with <emphasis>\</emphasis>. |
| 130 |
For example, the UTF-8 string <emphasis>føl,你好</emphasis> will be printed |
| 131 |
as <emphasis>f\303\270l\54\344\275\240\345\245\275</emphasis>. |
| 132 |
</para> |
| 133 |
<para> |
| 134 |
If the specified process is not |
| 135 |
authorized, <command>pkcheck</command> exits with a return value |
| 136 |
of 1 and a diagnostic message is printed on standard error. Details |
| 137 |
are printed on standard output. |
| 138 |
</para> |
| 139 |
<para> |
| 140 |
If the specified process is not |
| 141 |
authorized because no suitable authentication agent is available or if the |
| 142 |
<option>--allow-user-interaction</option> wasn't passed, <command>pkcheck</command> |
| 143 |
exits with a return value of 2 and a diagnostic message is printed on standard error. |
| 144 |
Details are printed on standard output. |
| 145 |
</para> |
| 146 |
<para> |
| 147 |
If the specified process is not authorized because the |
| 148 |
authentication dialog / request was dismissed by the user, |
| 149 |
<command>pkcheck</command> exits with a return value of 3 and a |
| 150 |
diagnostic message is printed on standard error. Details are |
| 151 |
printed on standard output. |
| 152 |
</para> |
| 153 |
<para> |
| 154 |
If an error occurred while checking for authorization, <command>pkcheck</command> exits |
| 155 |
with a return value of 127 with a diagnostic message printed on standard error. |
| 156 |
</para> |
| 157 |
<para> |
| 158 |
If one or more of the options passed are malformed, <command>pkcheck</command> exits |
| 159 |
with a return value of 126. If stdin is a tty, then this manual page is also shown. |
| 160 |
</para> |
| 161 |
</refsect1> |
| 162 |
|
| 163 |
<refsect1 id="pkcheck-notes"> |
| 164 |
<title>NOTES</title> |
| 165 |
<para> |
| 166 |
Do not use either the bare <replaceable>pid</replaceable> or |
| 167 |
<replaceable>pid,start-time</replaceable> syntax forms for |
| 168 |
<option>--process</option>. There are race conditions in both. |
| 169 |
New code should always use |
| 170 |
<replaceable>pid,pid-start-time,uid</replaceable>. The value of |
| 171 |
<replaceable>start-time</replaceable> can be determined by |
| 172 |
consulting e.g. the |
| 173 |
<citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| 174 |
file system depending on the operating system. If fewer than 3 |
| 175 |
arguments are passed, <command>pkcheck</command> will attempt to |
| 176 |
look up them up internally, but note that this may be racy. |
| 177 |
</para> |
| 178 |
<para> |
| 179 |
If your program is a daemon with e.g. a custom Unix domain |
| 180 |
socket, you should determine the <replaceable>uid</replaceable> |
| 181 |
parameter via operating system mechanisms such as |
| 182 |
<literal>PEERCRED</literal>. |
| 183 |
</para> |
| 184 |
</refsect1> |
| 185 |
|
| 186 |
<refsect1 id="pkcheck-auth-agent"><title>AUTHENTICATION AGENT</title> |
| 187 |
<para> |
| 188 |
<command>pkcheck</command>, like any other polkit |
| 189 |
application, will use the authentication agent registered for |
| 190 |
the process in question. However, if no authentication agent is |
| 191 |
available, then <command>pkcheck</command> can register its own |
| 192 |
textual authentication agent if the option |
| 193 |
<option>--enable-internal-agent</option> is passed. |
| 194 |
</para> |
| 195 |
</refsect1> |
| 196 |
|
| 197 |
<refsect1 id="pkcheck-author"><title>AUTHOR</title> |
| 198 |
<para> |
| 199 |
Written by David Zeuthen <email>[email protected]</email> with |
| 200 |
a lot of help from many others. |
| 201 |
</para> |
| 202 |
</refsect1> |
| 203 |
|
| 204 |
<refsect1 id="pkcheck-bugs"> |
| 205 |
<title>BUGS</title> |
| 206 |
<para> |
| 207 |
Please send bug reports to either the distribution or the |
| 208 |
polkit-devel mailing list, |
| 209 |
see <ulink url="https://github.com/polkit-org/polkit#bugs-and-development"/>. |
| 210 |
</para> |
| 211 |
</refsect1> |
| 212 |
|
| 213 |
<refsect1 id="pkcheck-see-also"> |
| 214 |
<title>SEE ALSO</title> |
| 215 |
<para> |
| 216 |
<link linkend="polkit.8"><citerefentry><refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>, |
| 217 |
<link linkend="polkitd.8"><citerefentry><refentrytitle>polkitd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>, |
| 218 |
<link linkend="pkaction.1"><citerefentry><refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>, |
| 219 |
<link linkend="pkexec.1"><citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>, |
| 220 |
<link linkend="pkttyagent.1"><citerefentry><refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum></citerefentry></link> |
| 221 |
</para> |
| 222 |
</refsect1> |
| 223 |
</refentry> |