Merge changes from CUPS 1.4svn-r8628.

[thirdparty/cups.git] / cups / api-filter.shtml

diff --git a/cups/api-filter.shtml b/cups/api-filter.shtml
index 7d2b469738e8e443296fbdc36d9ee942199fb38a..49bf24be3657c7398f83f095cc2c2b9efa4f9dd1 100644 (file)
--- a/cups/api-filter.shtml
+++ b/cups/api-filter.shtml
@@ -4,7 +4,7 @@
   Filter and backend programming introduction for the Common UNIX Printing
   System (CUPS).
 
-  Copyright 2007-2008 by Apple Inc.
+  Copyright 2007-2009 by Apple Inc.
   Copyright 1997-2006 by Easy Software Products, all rights reserved.
 
   These coded instructions, statements, and computer programs are the
@@ -49,6 +49,12 @@ the remaining filters read from the standard input and write to the standard
 output. The backend is the last filter in the chain and writes to the
 device.</p>
 
+<p>Filters are always run as a non-privileged user, typically "lp", with no
+connection to the user's desktop. Backends are run either as a non-privileged
+user or as root if the file permissions do not allow user or group execution.
+The <a href="#PERMISSIONS">file permissions</a> section talks about this in
+more detail.</p>
+
 <h3><a name="SECURITY">Security Considerations</a></h3>
 
 <p>It is always important to use security programming practices. Filters and
@@ -61,7 +67,7 @@ specify an arbitrary file path to a separator page, template, or other file
 used by the filter since that can lead to an unauthorized disclosure of
 information. <em>Always</em> treat input as suspect and validate it!</p>
 
-<p>If you are developing a backend that runs as root, make sure to check for
+<p>If you are developing a backend that runs as root , make sure to check for
 potential buffer overflows, integer under/overflow conditions, and file
 accesses since these can lead to privilege escalations. When writing files,
 always validate the file path and <em>never</em> allow a user to determine
@@ -75,10 +81,23 @@ user may not be the same as the local user and/or there may not be a local home
 directory to write to.</p>
 
 <p>In addition, some operating systems provide additional security mechanisms
-that further limit file system access, even for backends running as root.  On
+that further limit file system access, even for backends running as root. On
 Mac OS X, for example, no backend may write to a user's home directory.</p>
 </blockquote>
 
+<h3><a name="PERMISSIONS">File Permissions</a></h3>
+
+<p>For security reasons, CUPS will only run filters and backends that are owned
+by root and do not have world write permissions. The recommended permissions for
+filters and backends are 0555 - read and execute but no write. Backends that
+must run as root should use permissions of 0500 - read and execute by root, no
+access for other users. Write permissions can be enabled for the root user
+only.</p>
+
+<p>To avoid a warning message, the directory containing your filter(s) must also
+be owned by root and have world write disabled - permissions of 0755 or 0555 are
+strongly encouraged.</p>
+
 <h3><a name="TEMPFILES">Temporary Files</a></h3>
 
 <p>Temporary files should be created in the directory specified by the