| blob | f5aff0c6c2227ab4e2c8502c1e9f7eb767a2bb4d |
1 .\" Split out of Xserver.man, which was covered by this notice:
2 .\" Copyright 1984 - 1991, 1993, 1994, 1998 The Open Group
3 .\"
4 .\" Permission to use, copy, modify, distribute, and sell this software and its
5 .\" documentation for any purpose is hereby granted without fee, provided that
6 .\" the above copyright notice appear in all copies and that both that
7 .\" copyright notice and this permission notice appear in supporting
8 .\" documentation.
9 .\"
10 .\" The above copyright notice and this permission notice shall be included
11 .\" in all copies or substantial portions of the Software.
12 .\"
13 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
14 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
15 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
16 .\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
17 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
18 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
19 .\" OTHER DEALINGS IN THE SOFTWARE.
20 .\"
21 .\" Except as contained in this notice, the name of The Open Group shall
22 .\" not be used in advertising or otherwise to promote the sale, use or
23 .\" other dealings in this Software without prior written authorization
24 .\" from The Open Group.
25 .\" $XFree86: xc/programs/Xserver/Xserver.man,v 3.31 2004/01/10 22:27:46 dawes Exp $
26 .\" shorthand for double quote that works everywhere.
27 .ds q \N'34'
28 .TH SecurityPolicy __filemansuffix__ __xorgversion__
29 .SH NAME
30 SecurityPolicy \- X Window System SECURITY Extension Policy file format
31 .SH DESCRIPTION
32 The SECURITY extension to the X Window System uses a policy file to determine
33 which operations should be allowed or denied. The default location for this
34 file is
35 .IR __projectroot__/lib/xserver/SecurityPolicy .
36 .PP
37 The syntax of the security policy file is as follows.
38 Notation: "*" means zero or more occurrences of the preceding element,
39 and "+" means one or more occurrences. To interpret <foo/bar>, ignore
40 the text after the /; it is used to distinguish between instances of
41 <foo> in the next section.
42 .PP
43 .nf
44 <policy file> ::= <version line> <other line>*
46 <version line> ::= <string/v> '\en'
48 <other line > ::= <comment> | <access rule> | <site policy> | <blank line>
50 <comment> ::= # <not newline>* '\en'
52 <blank line> ::= <space> '\en'
54 <site policy> ::= sitepolicy <string/sp> '\en'
56 <access rule> ::= property <property/ar> <window> <perms> '\en'
58 <property> ::= <string>
60 <window> ::= any | root | <required property>
62 <required property> ::= <property/rp> | <property with value>
64 <property with value> ::= <property/rpv> = <string/rv>
66 <perms> ::= [ <operation> | <action> | <space> ]*
68 <operation> ::= r | w | d
70 <action> ::= a | i | e
72 <string> ::= <dbl quoted string> | <single quoted string> | <unquoted string>
74 <dbl quoted string> ::= <space> " <not dquote>* " <space>
76 <single quoted string> ::= <space> ' <not squote>* ' <space>
78 <unquoted string> ::= <space> <not space>+ <space>
80 <space> ::= [ ' ' | '\et' ]*
82 Character sets:
84 <not newline> ::= any character except '\en'
85 <not dquote> ::= any character except "
86 <not squote> ::= any character except '
87 <not space> ::= any character except those in <space>
88 .fi
89 .PP
90 The semantics associated with the above syntax are as follows.
91 .PP
92 <version line>, the first line in the file, specifies the file format
93 version. If the server does not recognize the version <string/v>, it
94 ignores the rest of the file. The version string for the file format
95 described here is "version-1" .
96 .PP
97 Once past the <version line>, lines that do not match the above syntax
98 are ignored.
99 .PP
100 <comment> lines are ignored.
101 .PP
102 <sitepolicy> lines are currently ignored. They are intended to
103 specify the site policies used by the XC-QUERY-SECURITY-1
104 authorization method.
105 .PP
106 <access rule> lines specify how the server should react to untrusted
107 client requests that affect the X Window property named <property/ar>.
108 The rest of this section describes the interpretation of an
109 <access rule>.
110 .PP
111 For an <access rule> to apply to a given instance of <property/ar>,
112 <property/ar> must be on a window that is in the set of windows
113 specified by <window>. If <window> is any, the rule applies to
114 <property/ar> on any window. If <window> is root, the rule applies to
115 <property/ar> only on root windows.
116 .PP
117 If <window> is <required property>, the following apply. If <required
118 property> is a <property/rp>, the rule applies when the window also
119 has that <property/rp>, regardless of its value. If <required
120 property> is a <property with value>, <property/rpv> must also have
121 the value specified by <string/rv>. In this case, the property must
122 have type STRING and format 8, and should contain one or more
123 null-terminated strings. If any of the strings match <string/rv>, the
124 rule applies.
125 .PP
126 The definition of string matching is simple case-sensitive string
127 comparison with one elaboration: the occurrence of the character '*' in
128 <string/rv> is a wildcard meaning "any string." A <string/rv> can
129 contain multiple wildcards anywhere in the string. For example, "x*"
130 matches strings that begin with x, "*x" matches strings that end with
131 x, "*x*" matches strings containing x, and "x*y*" matches strings that
132 start with x and subsequently contain y.
133 .PP
134 There may be multiple <access rule> lines for a given <property/ar>.
135 The rules are tested in the order that they appear in the file. The
136 first rule that applies is used.
137 .PP
138 <perms> specify operations that untrusted clients may attempt, and
139 the actions that the server should take in response to those operations.
140 .PP
141 <operation> can be r (read), w (write), or d (delete). The following
142 table shows how X Protocol property requests map to these operations
143 in the X.Org server implementation.
144 .PP
145 .nf
146 GetProperty r, or r and d if delete = True
147 ChangeProperty w
148 RotateProperties r and w
149 DeleteProperty d
150 ListProperties none, untrusted clients can always list all properties
151 .fi
152 .PP
153 <action> can be a (allow), i (ignore), or e (error). Allow means
154 execute the request as if it had been issued by a trusted client.
155 Ignore means treat the request as a no-op. In the case of
156 GetProperty, ignore means return an empty property value if the
157 property exists, regardless of its actual value. Error means do not
158 execute the request and return a BadAtom error with the atom set to
159 the property name. Error is the default action for all properties,
160 including those not listed in the security policy file.
161 .PP
162 An <action> applies to all <operation>s that follow it, until the next
163 <action> is encountered. Thus, irwad means ignore read and write,
164 allow delete.
165 .PP
166 GetProperty and RotateProperties may do multiple operations (r and d,
167 or r and w). If different actions apply to the operations, the most
168 severe action is applied to the whole request; there is no partial
169 request execution. The severity ordering is: allow < ignore < error.
170 Thus, if the <perms> for a property are ired (ignore read, error
171 delete), and an untrusted client attempts GetProperty on that property
172 with delete = True, an error is returned, but the property value is
173 not. Similarly, if any of the properties in a RotateProperties do not
174 allow both read and write, an error is returned without changing any
175 property values.
176 .PP
177 Here is an example security policy file.
178 .PP
179 .ta 3i 4i
180 .nf
181 version-1
183 XCOMM Allow reading of application resources, but not writing.
184 property RESOURCE_MANAGER root ar iw
185 property SCREEN_RESOURCES root ar iw
187 XCOMM Ignore attempts to use cut buffers. Giving errors causes apps to crash,
188 XCOMM and allowing access may give away too much information.
189 property CUT_BUFFER0 root irw
190 property CUT_BUFFER1 root irw
191 property CUT_BUFFER2 root irw
192 property CUT_BUFFER3 root irw
193 property CUT_BUFFER4 root irw
194 property CUT_BUFFER5 root irw
195 property CUT_BUFFER6 root irw
196 property CUT_BUFFER7 root irw
198 XCOMM If you are using Motif, you probably want these.
199 property _MOTIF_DEFAULT_BINDINGS root ar iw
200 property _MOTIF_DRAG_WINDOW root ar iw
201 property _MOTIF_DRAG_TARGETS any ar iw
202 property _MOTIF_DRAG_ATOMS any ar iw
203 property _MOTIF_DRAG_ATOM_PAIRS any ar iw
205 XCOMM The next two rules let xwininfo -tree work when untrusted.
206 property WM_NAME any ar
208 XCOMM Allow read of WM_CLASS, but only for windows with WM_NAME.
209 XCOMM This might be more restrictive than necessary, but demonstrates
210 XCOMM the <required property> facility, and is also an attempt to
211 XCOMM say "top level windows only."
212 property WM_CLASS WM_NAME ar
214 XCOMM These next three let xlsclients work untrusted. Think carefully
215 XCOMM before including these; giving away the client machine name and command
216 XCOMM may be exposing too much.
217 property WM_STATE WM_NAME ar
218 property WM_CLIENT_MACHINE WM_NAME ar
219 property WM_COMMAND WM_NAME ar
221 XCOMM To let untrusted clients use the standard colormaps created by
222 XCOMM xstdcmap, include these lines.
223 property RGB_DEFAULT_MAP root ar
224 property RGB_BEST_MAP root ar
225 property RGB_RED_MAP root ar
226 property RGB_GREEN_MAP root ar
227 property RGB_BLUE_MAP root ar
228 property RGB_GRAY_MAP root ar
230 XCOMM To let untrusted clients use the color management database created
231 XCOMM by xcmsdb, include these lines.
232 property XDCCC_LINEAR_RGB_CORRECTION root ar
233 property XDCCC_LINEAR_RGB_MATRICES root ar
234 property XDCCC_GRAY_SCREENWHITEPOINT root ar
235 property XDCCC_GRAY_CORRECTION root ar
237 XCOMM To let untrusted clients use the overlay visuals that many vendors
238 XCOMM support, include this line.
239 property SERVER_OVERLAY_VISUALS root ar
241 XCOMM Dumb examples to show other capabilities.
243 XCOMM oddball property names and explicit specification of error conditions
244 property "property with spaces" 'property with "' aw er ed
246 XCOMM Allow deletion of Woo-Hoo if window also has property OhBoy with value
247 XCOMM ending in "son". Reads and writes will cause an error.
248 property Woo-Hoo OhBoy = "*son" ad
250 .fi
251 .SH FILES
252 .TP 30
253 .I __projectroot__/lib/xserver/SecurityPolicy
254 Default X server security policy
255 .SH "SEE ALSO"
256 .PP
257 \fIXserver\fp(__appmansuffix__),
258 .I "Security Extension Specification"