Move SecurityPolicy file format from Xserver(1) to it's own man page

Don't make users looking for Xserver information page through pages of
details only interesting to the handful of people writing security policies.

3 files changed, 277 insertions, 218 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 0ac533e18..ce1979d4f 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,25 +1,35 @@
 appmandir = $(APP_MAN_DIR)
+filemandir = $(FILE_MAN_DIR)
 
 # Xserver.man covers options generic to all X servers built in this tree
+# (i.e. those handled in the os/utils.c options processing instead of in
+#  the DDX-level options processing)
 appman_PRE = Xserver.man.pre
+fileman_PRE = SecurityPolicy.man.pre
 
 appman_PROCESSED = $(appman_PRE:man.pre=man)
+fileman_PROCESSED = $(fileman_PRE:man.pre=man)
 
 appman_DATA = $(appman_PRE:man.pre=@APP_MAN_SUFFIX@)
+fileman_DATA = $(fileman_PRE:man.pre=@FILE_MAN_SUFFIX@)
 
-BUILT_SOURCES = $(appman_PROCESSED)
+BUILT_SOURCES = $(appman_PROCESSED) $(fileman_PROCESSED)
 
-CLEANFILES = $(appman_PROCESSED) $(appman_DATA)
+CLEANFILES = $(appman_PROCESSED) $(appman_DATA) \
+		$(fileman_PROCESSED) $(fileman_DATA)
 
 include $(top_srcdir)/cpprules.in
 
 .man.$(APP_MAN_SUFFIX):
 	cp $< $@
 
+.man.$(FILE_MAN_SUFFIX):
+	cp $< $@
+
 EXTRAMANDEFS = -D__default_font_path__="`echo $(COMPILEDDEFAULTFONTPATH) | sed -e 's/,/, /g'`"
 
 # Docs about X server internals that we ship with source but don't install
 DEVEL_DOCS = smartsched
 
 
-EXTRA_DIST = $(DEVEL_DOCS) $(appman_PRE)
+EXTRA_DIST = $(DEVEL_DOCS) $(appman_PRE) $(fileman_PRE)
diff --git a/doc/SecurityPolicy.man.pre b/doc/SecurityPolicy.man.pre
new file mode 100644
index 000000000..f5aff0c6c
--- /dev/null
+++ b/doc/SecurityPolicy.man.pre
@@ -0,0 +1,258 @@
+.\" 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"
diff --git a/doc/Xserver.man.pre b/doc/Xserver.man.pre
index cca58b135..aac3b51c3 100644
--- a/doc/Xserver.man.pre
+++ b/doc/Xserver.man.pre
@@ -414,221 +414,8 @@ X servers that support the SECURITY extension accept the following option:
 causes the server to attempt to read and interpret filename as a security
 policy file with the format described below.  The file is read at server
 startup and reread at each server reset.
-.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 Open Group 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
+The syntax of the security policy file is described in 
+\fISecurityPolicy\fP(__filemansuffix__).
 .SH "NETWORK CONNECTIONS"
 The X server supports client connections via a platform-dependent subset of
 the following transport types: TCP\/IP, Unix Domain sockets, DECnet,
@@ -757,6 +544,9 @@ Error log file for display number \fBn\fP if run from \fIinit\fP(__adminmansuffi
 .TP 30
 .I __projectroot__/lib/X11/xdm/xdm-errors
 Default error log file if the server is run from \fIxdm\fP(1)
+.TP 30
+.I __projectroot__/lib/xserver/SecurityPolicy
+Default X server security policy
 .SH "SEE ALSO"
 General information: \fIX\fP(__miscmansuffix__)
 .PP
@@ -771,6 +561,7 @@ Fonts: \fIbdftopcf\fP(1), \fImkfontdir\fP(1), \fImkfontscale\fP(1),
 .PP
 Security: \fIXsecurity\fP(__miscmansuffix__), \fIxauth\fP(1), \fIXau\fP(1), 
 \fIxdm\fP(1), \fIxhost\fP(1), \fIxfwp\fP(1),
+\fISecurityPolicy\fP(__filemansuffix__),
 .I "Security Extension Specification"
 .PP
 Starting the server: \fIxdm\fP(1), \fIxinit\fP(1)