margin-left: 36pt;
}
+DL.man DD {
+ margin-left: 5em;
+}
+
+DL.man DT {
+ margin-left: 0;
+}
+
+PRE.man {
+ margin: 0;
+}
+
PRE.example {
background: #eeeeee;
border: dotted thin #999999;
<body>
<div class='body'>
<!--
- "$Id: api-filter.header 7616 2008-05-28 00:34:13Z mike $"
-
Filter and backend programming header for CUPS.
- Copyright 2008-2014 by Apple Inc.
+ Copyright 2008-2016 by Apple Inc.
These coded instructions, statements, and computer programs are the
property of Apple Inc. and are protected by Federal copyright
<tr>
<th>Headers</th>
<th>cups/backend.h<br>
+ cups/ppd.h<br>
cups/sidechannel.h</th>
</tr>
</thead>
<li><a href="#COMMUNICATING_FILTER">Communicating with Filters</a></li>
<li><a href="#SNMP">Doing SNMP Queries with Network Printers</a></li>
</ul></li>
+<li><a href="#SANDBOXING">Sandboxing on macOS</a></li>
<li><a href="#FUNCTIONS">Functions</a><ul class="code">
<li><a href="#cupsBackChannelRead" title="Read data from the backchannel.">cupsBackChannelRead</a></li>
<li><a href="#cupsBackChannelWrite" title="Write data to the backchannel.">cupsBackChannelWrite</a></li>
</ul></li>
</ul>
<!--
- "$Id: api-filter.shtml 7677 2008-06-19 23:22:19Z mike $"
-
Filter and backend programming introduction for CUPS.
- Copyright 2007-2013 by Apple Inc.
+ Copyright 2007-2016 by Apple Inc.
Copyright 1997-2006 by Easy Software Products, all rights reserved.
These coded instructions, statements, and computer programs are the
<p>In addition, some operating systems provide additional security mechanisms
that further limit file system access, even for backends running as root. On
-OS X, for example, no backend may write to a user's home directory.</p>
+macOS, for example, no backend may write to a user's home directory. See the <a href="#SANDBOXING">Sandboxing on macOS</a> section for more information.</p>
</blockquote>
<h3><a name="SIGNALS">Canceled Jobs and Signal Handling</a></h3>
<dt>APPLE_LANGUAGE</dt>
<dd>The Apple language identifier associated with the job
- (OS X only).</dd>
+ (macOS only).</dd>
<dt>CHARSET</dt>
<dd>The job character set, typically "utf-8".</dd>
<dd>Sets or clears printer-state-reason keywords for the current queue.
Typically this is used to indicate persistent media, ink, toner, and
configuration conditions or errors on a printer.
- <a href='#TABLE2'>Table 2</a> lists the standard state keywords -
+ <a href='#TABLE2'>Table 2</a> lists some of the standard "printer-state-reasons" keywords from the <a href="http://www.iana.org/assignments/ipp-registrations/ipp-registrations.xhtml#ipp-registrations-4">IANA IPP Registry</a> -
use vendor-prefixed ("com.example.foo") keywords for custom states. See
<a href="#MANAGING_STATE">Managing Printer State in a Filter</a> for more
information.
<blockquote><b>Note:</b>
<p>"STATE:" messages often provide visible alerts to the user. For example,
-on OS X setting a printer-state-reason value with an "-error" or
+on macOS setting a printer-state-reason value with an "-error" or
"-warning" suffix will cause the printer's dock item to bounce if the
corresponding reason is localized with a cupsIPPReason keyword in the
printer's PPD file.</p>
<a href="#cupsSideChannelSNMPWalk">cupsSNMPSideChannelWalk</a>(".1.3.6.1.2.1.43", 5.0, my_callback, my_data);
</pre>
+
+<h2><a name="SANDBOXING">Sandboxing on macOS</a></h2>
+
+<p>Starting with macOS 10.6, filters and backends are run inside a security "sandbox" which further limits (beyond the normal UNIX user/group permissions) what a filter or backend can do. This helps to both secure the printing system from malicious software and enforce the functional separation of components in the CUPS filter chain. What follows is a list of actions that are explicitly allowed for all filters and backends:</p>
+
+<ol>
+
+ <li>Reading of files: pursuant to normal UNIX file permissions, filters and backends can read files for the current job from the <var>/private/var/spool/cups</var> directory and other files on mounted filesystems <em>except</em> for user home directories under <var>/Users</var>.</li>
+
+ <li>Writing of files: pursuant to normal UNIX file permissions, filters and backends can read/write files to the cache directory specified by the <code>CUPS_CACHEDIR</code> environment variable, to the state directory specified by the <code>CUPS_STATEDIR</code> environment variable, to the temporary directory specified by the <code>TMPDIR</code> environment variable, and under the <var>/private/var/db</var>, <var>/private/var/folders</var>, <var>/private/var/lib</var>, <var>/private/var/mysql</var>, <var>/private/var/run</var>, <var>/private/var/spool</var> (except <var>/private/var/spool/cups</var>), <var>/Library/Application Support</var>, <var>/Library/Caches</var>, <var>/Library/Logs</var>, <var>/Library/Preferences</var>, <var>/Library/WebServer</var>, and <var>/Users/Shared</var> directories.</li>
+
+ <li>Execution of programs: pursuant to normal UNIX file permissions, filters and backends can execute any program not located under the <var>/Users</var> directory. Child processes inherit the sandbox and are subject to the same restrictions as the parent.</li>
+
+ <li>Bluetooth and USB: backends can access Bluetooth and USB printers through IOKit. <em>Filters cannot access Bluetooth and USB printers directly.</em></li>
+
+ <li>Network: filters and backends can access UNIX domain sockets under the <var>/private/tmp</var>, <var>/private/var/run</var>, and <var>/private/var/tmp</var> directories. Backends can also create IPv4 and IPv6 TCP (outgoing) and UDP (incoming and outgoing) socket, and bind to local source ports. <em>Filters cannot directly create IPv4 and IPv6 TCP or UDP sockets.</em></li>
+
+ <li>Notifications: filters and backends can send notifications via the Darwin <code>notify_post()</code> API.</li>
+
+</ol>
+
+<blockquote><b>Note:</b> The sandbox profile used in CUPS 2.0 still allows some actions that are not listed above - these privileges will be removed over time until the profile matches the list above.</blockquote>
<h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
-<h3 class="function"><span class="info"> CUPS 1.2/
OS X 10.5 </span><a name="cupsBackChannelRead">cupsBackChannelRead</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2/
macOS 10.5 </span><a name="cupsBackChannelRead">cupsBackChannelRead</a></h3>
<p class="description">Read data from the backchannel.</p>
<p class="code">
ssize_t cupsBackChannelRead (<br>
return immediately if there is no data, -1.0 to wait for data indefinitely.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2/
OS X 10.5 </span><a name="cupsBackChannelWrite">cupsBackChannelWrite</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2/
macOS 10.5 </span><a name="cupsBackChannelWrite">cupsBackChannelWrite</a></h3>
<p class="description">Write data to the backchannel.</p>
<p class="code">
ssize_t cupsBackChannelWrite (<br>
indefinitely.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2/
OS X 10.5 </span><a name="cupsBackendDeviceURI">cupsBackendDeviceURI</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.2/
macOS 10.5 </span><a name="cupsBackendDeviceURI">cupsBackendDeviceURI</a></h3>
<p class="description">Get the device URI for a backend.</p>
<p class="code">
const char *cupsBackendDeviceURI (<br>
first.
</p>
-<h3 class="function"><span class="info"> CUPS 1.4/
OS X 10.6 </span><a name="cupsBackendReport">cupsBackendReport</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.4/
macOS 10.6 </span><a name="cupsBackendReport">cupsBackendReport</a></h3>
<p class="description">Write a device line from a backend.</p>
<p class="code">
void cupsBackendReport (<br>
device-info, device-id, and device-location strings.
</p>
-<h3 class="function"><span class="info"> CUPS 1.3/
OS X 10.5 </span><a name="cupsSideChannelDoRequest">cupsSideChannelDoRequest</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.3/
macOS 10.5 </span><a name="cupsSideChannelDoRequest">cupsSideChannelDoRequest</a></h3>
<p class="description">Send a side-channel command to a backend and wait for a response.</p>
<p class="code">
<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelDoRequest (<br>
update the value to contain the number of data bytes in the buffer.
</p>
-<h3 class="function"><span class="info"> CUPS 1.3/
OS X 10.5 </span><a name="cupsSideChannelRead">cupsSideChannelRead</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.3/
macOS 10.5 </span><a name="cupsSideChannelRead">cupsSideChannelRead</a></h3>
<p class="description">Read a side-channel message.</p>
<p class="code">
int cupsSideChannelRead (<br>
update the value to contain the number of data bytes in the buffer.
</p>
-<h3 class="function"><span class="info"> CUPS 1.4/
OS X 10.6 </span><a name="cupsSideChannelSNMPGet">cupsSideChannelSNMPGet</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.4/
macOS 10.6 </span><a name="cupsSideChannelSNMPGet">cupsSideChannelSNMPGet</a></h3>
<p class="description">Query a SNMP OID's value.</p>
<p class="code">
<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelSNMPGet (<br>
the printer does not respond to the SNMP query.
</p>
-<h3 class="function"><span class="info"> CUPS 1.4/
OS X 10.6 </span><a name="cupsSideChannelSNMPWalk">cupsSideChannelSNMPWalk</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.4/
macOS 10.6 </span><a name="cupsSideChannelSNMPWalk">cupsSideChannelSNMPWalk</a></h3>
<p class="description">Query multiple SNMP OID values.</p>
<p class="code">
<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelSNMPWalk (<br>
the printer does not respond to the first SNMP query.
</p>
-<h3 class="function"><span class="info"> CUPS 1.3/
OS X 10.5 </span><a name="cupsSideChannelWrite">cupsSideChannelWrite</a></h3>
+<h3 class="function"><span class="info"> CUPS 1.3/
macOS 10.5 </span><a name="cupsSideChannelWrite">cupsSideChannelWrite</a></h3>
<p class="description">Write a side-channel message.</p>
<p class="code">
int cupsSideChannelWrite (<br>
<dd class="description">Drain all pending output</dd>
<dt>CUPS_SC_CMD_GET_BIDI </dt>
<dd class="description">Return bidirectional capabilities</dd>
-<dt>CUPS_SC_CMD_GET_CONNECTED <span class="info"> CUPS 1.5/OS X 10.7 </span></dt>
+<dt>CUPS_SC_CMD_GET_CONNECTED <span class="info"> CUPS 1.5/macOS 10.7 </span></dt>
<dd class="description">Return whether the backend is "connected" to the printer </dd>
<dt>CUPS_SC_CMD_GET_DEVICE_ID </dt>
<dd class="description">Return the IEEE-1284 device ID</dd>
<dt>CUPS_SC_CMD_GET_STATE </dt>
<dd class="description">Return the device state</dd>
-<dt>CUPS_SC_CMD_SNMP_GET <span class="info"> CUPS 1.4/OS X 10.6 </span></dt>
+<dt>CUPS_SC_CMD_SNMP_GET <span class="info"> CUPS 1.4/macOS 10.6 </span></dt>
<dd class="description">Query an SNMP OID </dd>
-<dt>CUPS_SC_CMD_SNMP_GET_NEXT <span class="info"> CUPS 1.4/OS X 10.6 </span></dt>
+<dt>CUPS_SC_CMD_SNMP_GET_NEXT <span class="info"> CUPS 1.4/macOS 10.6 </span></dt>
<dd class="description">Query the next SNMP OID </dd>
<dt>CUPS_SC_CMD_SOFT_RESET </dt>
<dd class="description">Do a soft reset</dd>
projects / thirdparty / cups.git / blobdiff