.\" Split out of Xserver.man, which was covered by this notice:
.\" Copyright 1984 - 1991, 1993, 1994, 1998  The Open Group
.\"
.\" Permission to use, copy, modify, distribute, and sell this software and its
.\" documentation for any purpose is hereby granted without fee, provided that
.\" the above copyright notice appear in all copies and that both that
.\" copyright notice and this permission notice appear in supporting
.\" documentation.
.\"
.\" The above copyright notice and this permission notice shall be included
.\" in all copies or substantial portions of the Software.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
.\" OTHER DEALINGS IN THE SOFTWARE.
.\"
.\" Except as contained in this notice, the name of The Open Group shall
.\" not be used in advertising or otherwise to promote the sale, use or
.\" other dealings in this Software without prior written authorization
.\" from The Open Group.
.\" $XFree86: xc/programs/Xserver/Xserver.man,v 3.31 2004/01/10 22:27:46 dawes Exp $
.\" shorthand for double quote that works everywhere.
.ds q \N'34'
.TH SecurityPolicy __filemansuffix__ __xorgversion__
.SH NAME
SecurityPolicy \- X Window System SECURITY Extension Policy file format
.SH DESCRIPTION
The SECURITY extension to the X Window System uses a policy file to determine
which operations should be allowed or denied.   The default location for this
file is
.IR __projectroot__/lib/xserver/SecurityPolicy .
.PP
The syntax of the security policy file is as follows.
Notation: "*" means zero or more occurrences of the preceding element,
and "+" means one or more occurrences.  To interpret <foo/bar>, ignore
the text after the /; it is used to distinguish between instances of
<foo> in the next section.
.PP
.nf
<policy file> ::= <version line> <other line>*

<version line> ::= <string/v> '\en'

<other line > ::= <comment> | <access rule> | <site policy> | <blank line>

<comment> ::= # <not newline>* '\en'

<blank line> ::= <space> '\en'

<site policy> ::= sitepolicy <string/sp> '\en'

<access rule> ::= property <property/ar> <window> <perms> '\en'

<property> ::= <string>

<window> ::= any | root | <required property>

<required property> ::= <property/rp> | <property with value>

<property with value> ::= <property/rpv> = <string/rv>

<perms> ::= [ <operation> | <action> | <space> ]*

<operation> ::= r | w | d

<action> ::= a | i | e

<string> ::= <dbl quoted string> | <single quoted string> | <unquoted string>

<dbl quoted string> ::= <space> " <not dquote>* " <space>

<single quoted string> ::= <space> ' <not squote>* ' <space>

<unquoted string> ::= <space> <not space>+ <space>

<space> ::= [ ' ' | '\et' ]*

Character sets:

<not newline> ::= any character except '\en'
<not dquote>  ::= any character except "
<not squote>  ::= any character except '
<not space>   ::= any character except those in <space>
.fi
.PP
The semantics associated with the above syntax are as follows.
.PP
<version line>, the first line in the file, specifies the file format
version.  If the server does not recognize the version <string/v>, it
ignores the rest of the file.  The version string for the file format
described here is "version-1" .
.PP
Once past the <version line>, lines that do not match the above syntax
are ignored.
.PP
<comment> lines are ignored.
.PP
<sitepolicy> lines are currently ignored.  They are intended to
specify the site policies used by the XC-QUERY-SECURITY-1
authorization method.
.PP
<access rule> lines specify how the server should react to untrusted
client requests that affect the X Window property named <property/ar>.
The rest of this section describes the interpretation of an
<access rule>.
.PP
For an <access rule> to apply to a given instance of <property/ar>,
<property/ar> must be on a window that is in the set of windows
specified by <window>.  If <window> is any, the rule applies to
<property/ar> on any window.  If <window> is root, the rule applies to
<property/ar> only on root windows.
.PP
If <window> is <required property>, the following apply.  If <required
property> is a <property/rp>, the rule applies when the window also
has that <property/rp>, regardless of its value.  If <required
property> is a <property with value>, <property/rpv> must also have
the value specified by <string/rv>.  In this case, the property must
have type STRING and format 8, and should contain one or more
null-terminated strings.  If any of the strings match <string/rv>, the
rule applies.
.PP
The definition of string matching is simple case-sensitive string
comparison with one elaboration: the occurrence of the character '*' in
<string/rv> is a wildcard meaning "any string."  A <string/rv> can
contain multiple wildcards anywhere in the string.  For example, "x*"
matches strings that begin with x, "*x" matches strings that end with
x, "*x*" matches strings containing x, and "x*y*" matches strings that
start with x and subsequently contain y.
.PP
There may be multiple <access rule> lines for a given <property/ar>.
The rules are tested in the order that they appear in the file.  The
first rule that applies is used.
.PP
<perms> specify operations that untrusted clients may attempt, and
the actions that the server should take in response to those operations.
.PP
<operation> can be r (read), w (write), or d (delete).  The following
table shows how X Protocol property requests map to these operations
in the X.Org server implementation.
.PP
.nf
GetProperty	r, or r and d if delete = True
ChangeProperty	w
RotateProperties	r and w
DeleteProperty	d
ListProperties	none, untrusted clients can always list all properties
.fi
.PP
<action> can be a (allow), i (ignore), or e (error).  Allow means
execute the request as if it had been issued by a trusted client.
Ignore means treat the request as a no-op.  In the case of
GetProperty, ignore means return an empty property value if the
property exists, regardless of its actual value.  Error means do not
execute the request and return a BadAtom error with the atom set to
the property name.  Error is the default action for all properties,
including those not listed in the security policy file.
.PP
An <action> applies to all <operation>s that follow it, until the next
<action> is encountered.  Thus, irwad  means ignore read and write,
allow delete.
.PP
GetProperty and RotateProperties may do multiple operations (r and d,
or r and w).  If different actions apply to the operations, the most
severe action is applied to the whole request; there is no partial
request execution.  The severity ordering is: allow < ignore < error.
Thus, if the <perms> for a property are ired (ignore read, error
delete), and an untrusted client attempts GetProperty on that property
with delete = True, an error is returned, but the property value is
not.  Similarly, if any of the properties in a RotateProperties do not
allow both read and write, an error is returned without changing any
property values.
.PP
Here is an example security policy file.
.PP
.ta 3i 4i
.nf
version-1

XCOMM Allow reading of application resources, but not writing.
property RESOURCE_MANAGER	root	ar iw
property SCREEN_RESOURCES	root	ar iw

XCOMM Ignore attempts to use cut buffers.  Giving errors causes apps to crash,
XCOMM and allowing access may give away too much information.
property CUT_BUFFER0	root	irw
property CUT_BUFFER1	root	irw
property CUT_BUFFER2	root	irw
property CUT_BUFFER3	root	irw
property CUT_BUFFER4	root	irw
property CUT_BUFFER5	root	irw
property CUT_BUFFER6	root	irw
property CUT_BUFFER7	root	irw

XCOMM If you are using Motif, you probably want these.
property _MOTIF_DEFAULT_BINDINGS	root	ar iw
property _MOTIF_DRAG_WINDOW	root	ar iw
property _MOTIF_DRAG_TARGETS	any 	ar iw
property _MOTIF_DRAG_ATOMS	any 	ar iw
property _MOTIF_DRAG_ATOM_PAIRS	any 	ar iw

XCOMM The next two rules let xwininfo -tree work when untrusted.
property WM_NAME	any	ar

XCOMM Allow read of WM_CLASS, but only for windows with WM_NAME.
XCOMM This might be more restrictive than necessary, but demonstrates
XCOMM the <required property> facility, and is also an attempt to
XCOMM say "top level windows only."
property WM_CLASS	WM_NAME	ar

XCOMM These next three let xlsclients work untrusted.  Think carefully
XCOMM before including these; giving away the client machine name and command
XCOMM may be exposing too much.
property WM_STATE	WM_NAME	ar
property WM_CLIENT_MACHINE	WM_NAME	ar
property WM_COMMAND	WM_NAME	ar

XCOMM To let untrusted clients use the standard colormaps created by
XCOMM xstdcmap, include these lines.
property RGB_DEFAULT_MAP	root	ar
property RGB_BEST_MAP	root	ar
property RGB_RED_MAP	root	ar
property RGB_GREEN_MAP	root	ar
property RGB_BLUE_MAP	root	ar
property RGB_GRAY_MAP	root	ar

XCOMM To let untrusted clients use the color management database created
XCOMM by xcmsdb, include these lines.
property XDCCC_LINEAR_RGB_CORRECTION	root	ar
property XDCCC_LINEAR_RGB_MATRICES	root	ar
property XDCCC_GRAY_SCREENWHITEPOINT	root	ar
property XDCCC_GRAY_CORRECTION	root	ar

XCOMM To let untrusted clients use the overlay visuals that many vendors
XCOMM support, include this line.
property SERVER_OVERLAY_VISUALS	root	ar

XCOMM Dumb examples to show other capabilities.

XCOMM oddball property names and explicit specification of error conditions
property "property with spaces"	'property with "'	aw er ed

XCOMM Allow deletion of Woo-Hoo if window also has property OhBoy with value
XCOMM ending in "son".  Reads and writes will cause an error.
property Woo-Hoo	OhBoy = "*son"	ad

.fi
.SH FILES
.TP 30
.I __projectroot__/lib/xserver/SecurityPolicy
Default X server security policy
.SH "SEE ALSO"
.PP
\fIXserver\fp(__appmansuffix__),
.I "Security Extension Specification"